agent-mcp-hub

agent-mcp-hub

一个 MCP 服务，可将多个 CLI 编码 Agent——Codex、Cursor、 OpenCode、Claude 和 Antigravity——接入任意 MCP 客户端。

仅支持 stdio——这是有意为之。 该 Hub 不提供 Docker 镜像，也不提供 HTTP 传输（这两者已在 0.5.x 系列期间移除）。容器化或远程服务无法访问调用方的 仓库路径，也无法复用调用方的 CLI 登录状态——这会破坏产品约定的两方面。 Hub 会在你的机器上，以你的身份作为 MCP 客户端的子进程运行。

工具

工具	描述
codex	将提示词委派给 codex exec（通过 stdin 传入提示词）
cursor	将提示词委派给 cursor-agent -p（通过 stdin 传入提示词）
opencode	将提示词委派给 opencode run
claude	将提示词委派给 Claude Code CLI（通过 stdin 传入提示词）
agy	将提示词委派给 Google Antigravity（agy --print=…，提示词作为标志值传入）
run_all	同时向所有 Agent 发送相同提示词，并列展示结果
list_agents	查看已安装且位于 PATH 中的 Agent CLI
ping	健康检查

Agent 工具接受 prompt（必需）、model、cwd、timeoutMs（总运行时长上限， 默认值为 1800000 = 30 分钟）和 idleTimeoutMs（无活动时长上限，默认值为 300000 = 5 分钟）。请参阅长时间运行的任务与超时。

已知限制：opencode 的提示词不能以 - 开头（其 CLI 可能会将其解析为标志）； 工具会返回可操作的错误，而不会自行猜测。

为各 Agent 选择模型

模型 ID 因 Agent 而异，彼此不通用。 o3 对 agy 毫无意义，gemini-3.6-flash-low 对 codex 也毫无意义，而 opencode 使用自己的命名空间（opencode/big-pickle）。因此，在扇出调用中，单个 model 值最多只对一个 Agent 有效。

• run_all 接受 models——一个按 Agent 区分的映射。未列出的 Agent 会依次回退到 model，再回退到各自 CLI 的默认值。
• review_change 接受 runnerModel 和 reviewerModel，因此编写更改的 Agent 和评审更改的 Agent 可以使用不同的引擎和层级。model 仍是两者的回退值。

{
  "tool": "run_all",
  "arguments": {
    "prompt": "Explain the retry logic in src/exec.ts",
    "models": { "codex": "o3", "agy": "gemini-3.6-flash-low", "claude": "haiku" }
  }
}

如果 models 中的 Agent 名称未知，系统会拒绝该请求并列出已启用的 Agent—— 拼写错误不会悄悄回退到默认模型。

有效 ID 的查询方式：opencode models、cursor-agent models 和 agy models 可列出有效 ID。codex 和 claude 没有此类命令——codex 从 ~/.codex/config.toml 读取默认值，而 claude 接受文档中列出的别名 （opus、sonnet、haiku、fable）。请注意，claude models 不是 子命令：它会被当作提示词处理，因此生成的“模型列表”只是文本，并非权威信息来源。

错误处理

包装的 CLI 失败时，Hub 会对失败进行分类，并返回清晰、无 ANSI 转义码且可操作的 isError 结果——绝不会返回原始终端输出转储；结果会指出错误类别和确切的修复方法：

类别	修复示例
not_installed	安装 CLI（例如 npm i -g @openai/codex）／修复 PATH
not_authenticated	codex login · cursor-agent login · opencode auth login · claude → /login · agy → 首次运行时登录（或设置相应的 API 密钥）
not_configured	在 CLI 的配置中设置模型／提供商
timed_out	调高 timeoutMs，或检查 Agent／模型是否响应正常
stream_stalled	Agent 已连接网络，但其数据流持续中断（例如 cursor 位于 TLS 拦截代理之后）——请将该 Agent 视为不可用；调高 timeoutMs 无济于事
server_busy	稍后重试（上游速率限制，或本地 Agent 启动队列已满）
tool_failure	通用非零退出——消息中包含 (exit N) 和经过截断的输出末尾

例如，未经身份验证的 cursor 不再返回其 ANSI“按任意键登录”横幅，而会返回 cursor is not authenticated … Fix: run cursor-agent login``。

审查更改（review_change）

在 Git cwd 中运行 runner Agent 进行更改，捕获实际更改内容的 git diff，然后让 reviewer Agent 对该 diff 作出判断。返回 runner 的输出、diff（--stat），以及带有问题说明的 PASS / WARN / FAIL 判定。

输入： runner、reviewer（Agent 名称）、prompt、cwd（必须是 Git 工作树），可选的 runnerModel、reviewerModel、model（两者的回退选项）、 timeoutMs。

重要说明：

• 此设计支持跨 Agent 协作，例如由 codex 编写、claude 审查。

• 返回普通 Agent 工具不会公开的具体 diff。

• 新创建的（未跟踪）文件会连同其内容一起呈现给审查者（有大小限制：每个文件 64 KiB，最多 50 个文件；超出的内容会被截断并标记）。单独使用 git diff 会完全忽略这些文件。

• 如果工作树原本就有未提交的更改，diff 可能包含预先存在的更改（输出中会注明）。

• 可与客户端侧 stop-hooks 或 PR 阶段的 CI 审查配合使用，不能取代它们。

• 确认门控（MCP_CONFIRM）仍然适用。

• 审查者以最小权限运行，但这能提供多大保障取决于所用的 Agent。 审查者的提示词中嵌入了受攻击者影响的 diff，因此以只读模式运行，而不会获得 runner 所拥有的写入权限。以下五种方式中，只有两种是真正的限制：

  审查者	只读机制	是否强制执行？
  codex	-s read-only	是——操作系统级沙箱
  claude	--disallowedTools Write,Edit,…,Bash	是——运行框架级拒绝
  cursor	--trust --mode plan（不含 --force）	否——仅由模型自行遵守
  agy	不授予权限	部分——无头模式下自动拒绝，但不是沙箱
  opencode	无可用机制	否——不受限制

  如果需要真正生效的限制，请选择 codex 或 claude 作为审查者。 这是与使用 nonce 限定 diff 和一次性临时 cwd 相结合的纵深防御措施； 这些措施都不是沙箱。

{
  "tool": "review_change",
  "arguments": {
    "runner": "codex",
    "reviewer": "claude",
    "prompt": "Add retry with exponential backoff to the API client",
    "cwd": "/Users/you/projects/my-app"
  }
}

前置条件

安装并完成你要使用的 CLI 的身份验证（可任选）：

• Codex：npm i -g @openai/codex && codex login
• Cursor：curl https://cursor.com/install -fsS | bash && cursor-agent login
• OpenCode：npm i -g opencode-ai && opencode auth login
• Claude Code：npm i -g @anthropic-ai/claude-code && claude（首次运行时会登录）
• Antigravity：安装 Antigravity CLI（例如，brew install --cask antigravity-cli）， 然后运行一次 agy 并登录——它没有 login 子命令，且会将凭据存储在操作系统密钥环中， 因此无需设置 API 密钥环境变量

安装

推荐方式——全局安装（启动快速、可靠）： 安装一次指定版本， 然后让客户端调用 agent-mcp-hub 二进制文件。启动即时完成，客户端可可靠连接。

npm i -g [email protected]

Claude Code

claude mcp add agent-hub -- agent-mcp-hub

Cursor / 通用 mcp.json

{
  "mcpServers": {
    "agent-hub": {
      "command": "agent-mcp-hub"
    }
  }
}

零安装替代方案（npx）

无需全局安装，但 npx 每次启动都会重新解析软件包，因此首次启动较慢， 有时可能触发客户端的连接探测超时（服务本身没有问题——重试即可）。对于 持久化配置，建议使用全局安装。

claude mcp add agent-hub -- npx -y [email protected]
# mcp.json:  "command": "npx", "args": ["-y", "[email protected]"]

预发布版本 / 回退方案： 要测试尚未发布的提交，可直接从 GitHub 运行：npx -y github:blackaxgit/agent-mcp-hub#<tag-or-sha>。首次获取时会 从源代码构建，因此在 npm v12+ 中必须允许执行 prepare 脚本。

配置

MCP_AGENTS——要公开的 Agent 逗号分隔允许列表 （codex,cursor,opencode,claude,agy）。未设置或为空时会公开所有 Agent。被禁用的 Agent 不会提供工具，也不会出现在 list_agents/run_all 中。未知名称会在启动时 报错并列出有效名称，因此拼写错误不会导致 Agent 被静默禁用。

对于 stdio，请在客户端的 mcp.json 中设置：

{
  "mcpServers": {
    "agent-hub": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": { "MCP_AGENTS": "codex,claude" }
    }
  }
}

运行 Agent 前确认 — MCP_CONFIRM

将 MCP_CONFIRM=1（取值为 1/true/on/all；默认关闭），即可要求在任何 Agent 工具（以及 run_all）实际启动 CLI 前进行确认。服务会发送简短摘要（Agent · 提示词 · cwd · 模型）并等待：接受会运行 Agent，拒绝则不会运行任何内容，并返回终止取消状态。

这使用标准 MCP elicitation 能力，因此与客户端/IDE 无关——适用于任何支持表单 elicitation 的 MCP 客户端（Claude Code、Cursor、VS Code、Zed、Windsurf、自定义 SDK 客户端等）；确认机制依据的是协议能力，而非产品名称。不支持 elicitation 的客户端会透明地直接运行，不会弹出提示（不会卡住，也不会报错）。

{
  "mcpServers": {
    "agent-hub": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": { "MCP_CONFIRM": "1" }
    }
  }
}

长时间运行的任务与超时

复杂的 Agent 任务可能运行数分钟。hub 使用两个相互独立的计时器限制每次运行，让有进展的长时间任务得以继续，同时让真正卡住的任务快速失败：

• 空闲（无活动）超时 — idleTimeoutMs（每次调用）/ MCP_AGENT_IDLE_TIMEOUT_MS （环境变量），默认 300000（5 分钟）。每当 CLI 产生一个输出块，计时器都会重置，因此持续工作的 Agent（持续输出）不会触发该超时。如果 Agent 停止输出——例如 opencode 卡在无法访问的模型后端上——则在空闲时限到期后会被终止，并返回可采取行动的错误信息“没有输出——Agent 可能已卡住，或者其模型/后端无法访问”，而不是一直占用到总时限。
• 总运行时长上限 — timeoutMs（每次调用）/ MCP_AGENT_TIMEOUT_MS（环境变量），默认 1800000（30 分钟）。无论活动情况如何，都会强制执行的最长时限。

先触发的计时器会终止 Agent 的进程组。权衡：空闲计时器的重置依赖 CLI 持续输出中间内容。codex 和 opencode 会这样做；claude -p、cursor-agent -p 和 agy --print 则可能只输出最终结果，因此这些工具上的长时间无输出任务可能在 5 分钟后因空闲超时而被终止——对于这类任务，请调高 idleTimeoutMs / MCP_AGENT_IDLE_TIMEOUT_MS，或依赖总时长上限。

agy 是最典型的情况：它会在结束时一次性输出完整答案（经测量，12 行回复中的每一行都在同一时刻到达）；hub 会将其内部 --print-timeout 提高到 48 小时，因此 agy 自带的 5 分钟默认超时不会截断运行。因此，空闲计时器是 agy 防止真正卡住的唯一保护措施；对于长时间自主运行的 agy 任务，请合理设置 idleTimeoutMs。

Agent 运行期间，hub 会向请求了 MCP 进度通知的客户端（_meta.progressToken）发送通知，为长时间运行提供实时反馈。注意：在 Claude Code（stdio） 中，.mcp.json 里的每服务器请求 timeout（或其支持的 MCP_TOOL_TIMEOUT 环境变量）是固定的墙钟时限，进度不会重置该时限（默认约 28 小时）——如果你将其调低至最长运行时长以下，请调高。

升级

**全局安装：**安装新版本——MCP 配置中固定的 agent-mcp-hub 命令会在下次启动客户端时使用新版本：

npm i -g [email protected]

**npx（固定版本）：**在 MCP 配置中提升固定版本号——例如将所有位置的 [email protected] 改为 [email protected]。

**始终使用最新版本（不建议用于共享配置）：**使用 agent-mcp-hub@latest，而非固定版本。注意，npx 会按版本缓存，因此可能提供过期副本。使用 npx --prefer-online agent-mcp-hub 或 npx clear-npx-cache 强制重新获取。

固定版本可确保结果可复现，建议用于团队统一使用或纳入版本控制的 mcp.json 文件。

开发

npm install
npm test           # vitest
npm run typecheck  # strict TS over src + tests
npm run dev        # run from source over stdio
npm run build      # emit dist/

架构

纯适配器（src/adapters/*——提示词 → {args, stdin?}，不执行 I/O）→ 单一子进程边界（src/exec.ts）→ MCP stdio 服务（src/server.ts）。添加一个 Agent = 一个约 15 行的适配器文件 + src/registry.ts 中的一行。

许可证

Mozilla 公共许可证 2.0（MPL-2.0）。

0.5.2 之前发布的版本采用 MIT 许可证；这些版本的授权仍然有效。MPL-2.0 适用于 0.5.2 及之后的版本。