cs-agent-mcp

cs-agent-mcp 是一个本地 stdio MCP 服务。它把 Codex、Claude 等编码 Agent 统一成一组 cs_agent_* 工具，让根 Agent 可以创建、调用和管理子 Agent，子 Agent 也可以继续递归委派。

安装

运行环境：

• Node.js 22.13.0 或更高版本。

• 已安装并登录准备使用的本机 Agent，例如 codex 或 claude。

全局安装：

npm install -g cs-agent-mcp
cs-agent-mcp --version

也可以不做全局安装，直接通过 npm 启动：

npx -y cs-agent-mcp --version

无需安装 Claude 桌面应用，也无需为 MCP 再登录一次。Claude 子 Agent 会优先使用本机 claude 可执行文件和现有用户设置；Codex、Claude 都沿用当前用户已有的登录状态。首次调用 某个 Agent 时，如果对应 ACP 适配器尚未缓存，npm 可能下载适配器及其 SDK。这只是本地协议桥， 不是重新安装 Claude/Codex，也不需要手工配置适配器路径、端口或令牌。

Related MCP server: personal-mcp

配置

配置 Codex

全局安装后执行：

codex mcp add cs-agent -- cs-agent-mcp
codex mcp list

不做全局安装时执行：

codex mcp add cs-agent -- npx -y cs-agent-mcp

配置 Claude Code

全局安装后执行：

claude mcp add --scope user cs-agent -- cs-agent-mcp
claude mcp list

不做全局安装时执行：

claude mcp add --scope user cs-agent -- npx -y cs-agent-mcp

配置服务

Codex 和 Claude 已经可以在本机正常工作时，不需要创建服务配置文件。需要修改默认权限、 超时或 Agent 命令时，可以使用以下两个 JSON 文件：

1. 用户级配置：~/.cs-agent-mcp/config.json

2. 项目级配置：<cwd>/.cs-agent-mcprc.json

项目级值覆盖用户级值。<cwd> 是启动命令的工作目录，或通过 --cwd 显式指定的目录。

{
  "defaultAgent": "codex",
  "defaultPermissions": "approve-reads",
  "nonInteractivePermissions": "deny",
  "timeout": 1800,
  "agents": {
    "reviewer": {
      "command": "/absolute/path/to/acp-agent",
      "args": ["--stdio"]
    }
  },
  "mcpServers": [
    {
      "type": "stdio",
      "name": "project-tools",
      "command": "/absolute/path/to/project-tools-mcp",
      "args": []
    }
  ]
}

常用字段：

agents 中的命令必须提供 ACP stdio 接口，不能直接填一个只支持交互终端的普通 CLI。内置 codex 和 claude 已经配置了相应适配器，通常不应覆盖。

工作目录由 MCP roots 决定：客户端提供一个 workspace root 时，子 Agent 默认在该目录工作； 提供多个 roots 时，cs_agent_create 必须显式传入 cwd；客户端不支持 roots 时，服务使用 启动目录或 --cwd 的值；客户端声明支持 roots 但返回空集合时，服务拒绝启动工作区。 所有 cwd 都必须是位于客户端声明的 workspace roots 内的现有真实目录。

启动

完成 MCP 注册后，无需手工常驻进程。Codex 或 Claude 会在需要时自动启动 stdio 服务：

cs-agent-mcp

不做全局安装时对应命令是：

npx -y cs-agent-mcp

需要指定没有 roots 能力时的后备工作目录：

cs-agent-mcp --cwd /absolute/path/to/workspace

该命令通过 stdin/stdout 传输 MCP 协议，正常启动后不会打印交互式提示，也不会监听公网端口。 运行状态、Agent 会话和事件历史保存在 ~/.cs-agent-mcp/；同一 workspace 同时只能由一个 cs-agent-mcp 进程持有。

MCP 能力

典型流程是：先检查能力，再创建子 Agent，发送带幂等键的任务，循环等待结果，最后按需取消 Turn 或销毁 Agent。

sessionOptions 支持 model、systemPrompt、allowedTools 和 maxTurns。附件使用 { "mediaType": "...", "data": "<base64>" }。cs_agent_send 的 idempotencyKey 在同一调用者范围内全局去重；重试同一任务时应复用原键，向不同 Agent 发送任务时也必须使用不同的键。

persistent 模式要求服务重启后恢复原 ACP 会话，无法恢复时明确失败；oneshot 模式允许 底层运行时在原会话不可用时建立新会话，因此不承诺跨重连保留上下文。两种模式下的 Facade Agent 都可以接收多个串行 Turn，直到祖先调用 cs_agent_destroy。受管 Agent 不能销毁自己。 discardSession 依赖目标 ACP 适配器支持 session/close；不支持时会返回明确错误并保留可恢复 状态，普通销毁不受影响。

等待工具单次最多等待 30 秒。未完成时应使用返回的 Turn 修订号或 Event cursor 继续等待， 不要通过无限长的单次 MCP 调用阻塞宿主。

受管 Agent 会自动获得一个经过身份认证、仅回环访问的同一 Facade MCP 连接，因此 Claude 可以 再创建 Codex 子 Agent，Codex 也可以继续委派，无需为每一层配置 MCP。调用者只能查看和操作 自己的委派子树；同一 Agent 的 Turn 严格串行，不同 Agent 可以并行执行。默认限制为递归深度 4、受管 Agent 16 个、每个 Agent 排队 32 个 Turn、全局并发 Turn 8 个。

完整状态会持久化。服务重启后，历史 Message、Turn 和 Event 仍可查询；持久 Agent 会尝试加载 原 ACP 会话，无法恢复时会明确失败，不会静默创建一个丢失上下文的新会话。

架构与安全边界见 MCP 架构设计。