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，也不需要手工配置适配器路径、端口或令牌。

配置

配置 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": []
    }
  ]
}

常用字段：

字段	默认值	作用
defaultAgent	codex	根执行身份使用的默认 Agent 名称
defaultPermissions	approve-reads	approve-all、approve-reads 或 deny-all
nonInteractivePermissions	deny	无交互权限请求时选择 deny 或 fail
timeout	无限制	单次 Agent 调用的默认超时秒数
agents	内置注册表	新增或覆盖 ACP stdio Agent 命令
mcpServers	[]	注入每个受管 Agent 的其他 MCP 服务
auth	{}	ACP authenticate 方法与凭据的映射
authPolicy	skip	缺少匹配 ACP 凭据时选择 skip 或 fail

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。

工具	主要参数	能力
cs_agent_capabilities	probeAgents?	列出工具、限制、内置 Agent，并可真实探测指定 Agent
cs_agent_create	agent、name?、cwd?、mode?、sessionOptions?	创建使用持久或一次性 ACP 会话模式的受管 Agent
cs_agent_list	parentAgentId?、agent?、state?、cursor?、limit?	分页列出当前调用者可见的委派子树
cs_agent_status	agentId	查询生命周期、队列、权限和底层运行时状态
cs_agent_events	afterCursor?、agentId?、turnId?、limit?、waitMs?	增量读取结构化事件，支持最长 30 秒等待
cs_agent_send	agentId、content、idempotencyKey、attachments?、timeoutMs?	向子 Agent 的 FIFO 队列发送幂等任务，返回 messageId 和 turnId
cs_agent_get_message	messageId	读取一条不可变输入或回复消息
cs_agent_wait_message	turnId 或 messageId、waitMs?	等待回复、权限请求或无回复的终态
cs_agent_get_turn	turnId	读取 Turn 状态、修订号、错误和关联消息
cs_agent_wait_turn	turnId、afterRevision?、waitMs?	等待 Turn 状态变化或权限请求
cs_agent_respond_permission	permissionId、outcome	允许、拒绝或取消待处理权限请求
cs_agent_cancel	turnId、reason?	取消排队中或运行中的 Turn，并取消其未完成后代 Turn
cs_agent_destroy	agentId、cascade?、discardSession?	销毁 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 架构设计。