Agent Gateway MCP

A Windows-native MCP gateway that lets any MCP-capable host orchestrate local coding-agent CLIs as external workers.

Windows 原生的通用 CLI Agent 网关。Codex、Claude Desktop 或其他支持 stdio MCP 的宿主，可以统一调度本机 ZCode、Kimi Code、Claude Code、Codex CLI 和 Pi Coding Agent。

Why

Route routine work to lower-cost plans/models and reserve the controller for hard decisions.
Compare different agent harnesses with the same task and permissions.
Keep asynchronous lifecycle, logs, cancellation, resume and workspace safety behind one MCP API.
Prefer structured CLI protocols; never inject into an already-open interactive TUI.

MCP tools

agents_list, agents_spawn, agents_status, agents_wait, agents_logs, agents_cancel, and agents_resume.

Legacy Kimi compatibility tools remain available: kimi_status, kimi_run, kimi_resume, and kimi_list_sessions.

Install

Requirements: Windows, Node.js 20+, and at least one supported Agent CLI already installed and authenticated.

git clone https://github.com/Kvxw1105/agent-gateway-mcp.git
cd agent-gateway-mcp
npm ci
npm run build
npm test

Add the built server to any stdio MCP host. Generic JSON:

{
  "mcpServers": {
    "agent-gateway": {
      "command": "node",
      "args": ["C:\\absolute\\path\\agent-gateway-mcp\\dist\\src\\index.js"]
    }
  }
}

Codex TOML and generic JSON examples are in examples/. Restart the host after editing its MCP configuration.

Natural-language usage

The controller can translate requests such as:

“Let Pi inspect this repository without editing files.”
“让 Kimi 先定位问题；失败后再升级给 Codex。”
“Run the same read-only task with Pi and ZCode, then compare their harness behavior.”
“让两个 Agent 在各自 Git worktree 实现，最后只保留通过测试的方案。”

The reusable orchestration Skill is included under integrations/skills/agent-gateway-orchestrator. Install it for Codex, Claude Code, or both:

powershell -ExecutionPolicy Bypass -File scripts/install-skill.ps1 -TargetHost both

Provider configuration

The gateway auto-discovers common global npm layouts and executables on PATH. Override any provider without editing source:

Variable	Purpose
`AGENT_GATEWAY_<ID>_COMMAND`	Executable for `ZCODE`, `KIMI`, `CLAUDE`, `CODEX`, or `PI`
`AGENT_GATEWAY_<ID>_PREFIX_ARGS`	JSON array inserted before normal CLI arguments
`AGENT_GATEWAY_CODEX_MODEL`	Default Codex model
`AGENT_GATEWAY_PI_PROVIDER`	Default Pi provider; defaults to `opencode-go`
`AGENT_GATEWAY_PI_MODEL`	Default Pi model; defaults to `opencode-go/deepseek-v4-flash`
`AGENT_GATEWAY_PI_API_KEY_ENV`	Windows user-environment key read for Pi; defaults to `OPENCODE_API_KEY`
`AGENT_GATEWAY_CLAUDE_CLEAN_ENV=1`	Remove Anthropic endpoint overrides only for the Claude child process

For a JavaScript CLI installed in an unusual location, set both command and prefix arguments:

$env:AGENT_GATEWAY_ZCODE_COMMAND = 'C:\Program Files\nodejs\node.exe'
$env:AGENT_GATEWAY_ZCODE_PREFIX_ARGS = '["C:\\tools\\zcode\\bin\\zcode.js"]'

Secrets belong in the provider's credential store or Windows user environment. Do not put API keys in the repository, prompts, or MCP config.

Safety model

read-only is the default permission.
Concurrent writes to the same ordinary directory are rejected.
Parallel writers must use separate Git worktrees and set isolated_worktree=true.
Cancellation terminates the task process tree on Windows.
Resume starts a new non-interactive process; it never writes into an open TUI session.
Kimi prompt mode lacks a hard read-only flag, so its read-only boundary is explicitly reported as mixed.
Task state is currently in-memory; provider session IDs may still be resumed after an MCP server restart.

Development

npm test
npm run typecheck
npm run smoke
npm audit

The upstream ecosystem audit is in docs/audits/2026-08-13-windows-agent-gateway-ecosystem.md.

Current architecture decisions, limitations, and the prioritized handoff roadmap are in .context/handoff/2026-08-13-agent-gateway-handoff.md.

License

Apache-2.0. The supported Agent CLIs are separate products with their own licenses and terms; this repository does not redistribute them.