cs-agent-mcp

August 12, 2026 · View on GitHub

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@latest
cs-agent-mcp --version

选择正在使用的根 Agent 注册 MCP。Codex 用户执行：

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

Claude Code 用户执行：

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

新开一个 Codex 或 Claude Code 会话后，可以直接发送下面的任务：

请使用 cs-agent MCP 完成以下任务：
1. 先用 cs_agent_capabilities 探测 codex 和 claude。
2. 优先创建 codex 子 Agent；如果不可用，则创建 claude 子 Agent。
   让它审查当前仓库的改动。
3. 等待并读取回复，然后销毁子 Agent。
4. 最后向我总结审查结果。

根 Agent 会调用 cs_agent_* 工具完成创建、等待和销毁。完成 MCP 注册后，不需要手工常驻 cs-agent-mcp 进程。

其他安装方式

不做全局安装时，可以让 MCP 客户端通过 npm 直接启动当前最新版：

npx -y cs-agent-mcp@latest --version
codex mcp add cs-agent -- npx -y cs-agent-mcp@latest

Claude Code 对应命令是：

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

需要可重复的固定环境时，可以把 @latest 换成明确版本号。

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

受管 Claude 仍会保留用户的 skills、hooks、plugins 和无关 MCP。若 Claude 用户配置中存在直接或通过 npx、npm exec、pnpm dlx 启动 cs-agent-mcp 的 MCP 名称，服务会在受管 session 中用同名的身份受限 loopback 入口覆盖它，避免递归委派误用 Workspace root 身份。 Claude 用户配置不会被修改或复制；配置变更会在对应 Workspace 控制面重启后重新读取。当前自动覆盖范围是 ~/.claude.json 顶层的 user-scope MCP；不要在项目 .mcp.json 或 Claude local/project scope 另外注册指向 cs-agent-mcp 的 root 控制面，以免重新引入身份冲突。

支持的 Agent

支持级别	Agent	说明
重点实机支持	`codex`、`claude`	内置 ACP 适配器，并在发布验证中使用本机登录状态执行真实任务
ACP 兼容支持	`pi`、`openclaw`、`gemini`、`cursor`、`copilot`、`droid`、`fast-agent`、`grok-build`、`iflow`、`kilocode`、`kimi`、`kiro`、`mux`、`opencode`、`pool`、`qoder`、`qwen`、`trae`、`zeroclaw`	内置命令映射和通用 ACP client/runtime 测试通过；可用性取决于本机环境

“ACP 兼容支持”不是仅供展示的候选映射。这些 Agent 与 Codex、Claude 共用 Agent 创建和销毁、持久或 oneshot 会话、消息与 Turn、权限回传、取消、事件、批量等待和 Workspace 共享控制面。例如 pi 通过 pi-acp 启动，openclaw 使用原生 openclaw acp，gemini 使用原生 ACP 模式。不同支持级别的区别是发布门禁的实机覆盖范围，不是 MCP 编排能力不同。

pool 使用本机 pool acp，需要先安装 Pool CLI 并完成登录。zeroclaw 使用本机 zeroclaw acp；ZeroClaw 默认可能忽略 session/new 传入的 MCP servers，只有对应 Agent 配置启用 ACP MCP 后才能使用递归委派，因此不能仅凭 initialize 成功推断其子 Agent 能力。

建议先调用 cs_agent_capabilities 并通过 probeAgents 探测准备使用的 Agent。探测会真实启动对应 ACP server 并完成 initialize 握手，而不只是检查命令名称。也可以在 agents 配置中新增或覆盖任何提供 ACP stdio 接口的 Agent。

何时使用多 Agent

MCP 初始化信息和工具描述会主动提示调用 Agent 在以下场景考虑委派：

任务可以拆成相互独立、可并行验证的子任务。
需要不同 Agent runtime 承担互补角色，例如实现与独立审查。
子任务需要独立上下文、专门约束或较长时间运行，主 Agent 只负责协调结果。
当前结果需要第二个 Agent 给出独立证据，而不是在同一上下文中自我复核。

不要为很小、强顺序依赖、上下文无法独立描述，或当前 Agent 能直接快速完成的工作创建子 Agent。委派本身有启动、传递上下文和汇总结果的成本。

异构协作时先用 cs_agent_capabilities 探测准备使用的多个 Agent，再根据当前任务给它们分配互补角色。服务只报告配置名称、可用性和执行限制，不把容易过期的“某个品牌永远更擅长某类任务” 写成运行时事实。每个 cs_agent_send 都应给出自包含的目标、范围、约束、交付物和验证要求。

推荐工作流：

cs_agent_capabilities
  -> cs_agent_run_structured（单次严格 JSON 结果；原子创建、等待和销毁）
或
  -> cs_agent_create（按独立角色创建一个或多个 Agent）
  -> cs_agent_send（先给每个 Agent 发送自包含任务）
  -> cs_agent_wait_many（多个 Turn 使用 any/all 汇总；单 Turn 使用 wait_message）
  -> cs_agent_respond_permission / cs_agent_cancel（按需）
  -> cs_agent_destroy（不再需要时释放 Agent）

配置

配置服务

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

用户级配置：~/.cs-agent-mcp/config.json
项目级配置：<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 内的现有真实目录。

规范化后的 roots 集合也是共享边界。同一组 roots 即使顺序不同，也会连接到同一个本机控制面和同一棵 Agent 树；Codex、Claude 等多个根控制台可以交叉查看、等待、取消和销毁其中的任务。不同 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 协议，正常启动后不会打印交互式提示，也不会监听公网端口。前端会按需发现或启动一个仅绑定本机回环地址的 Broker；同一 workspace 的多个前端共享 Broker 内唯一的 Facade/runtime owner。最后一个前端离开后，Broker 会经过短暂 grace 再收束 runtime 并释放 workspace lock；grace 内重连不会更换 lock generation。运行状态、Agent 会话和事件历史保存在 ~/.cs-agent-mcp/，无需手工管理后台服务。

MCP 能力

典型流程是：先检查能力，再按独立角色创建子 Agent，发送带幂等键且可独立执行的任务，循环等待结果，最后按需取消 Turn 或销毁 Agent。MCP server instructions、工具 description 和输入 schema 字段说明都携带这套决策与编排提示，即使宿主只展示 tools/list 也能看到关键使用条件。

工具	主要参数	能力
`cs_agent_capabilities`	`probeAgents?`	列出工具、限制、内置 Agent，并可真实探测指定 Agent
`cs_agent_run_structured`	`agent`、`content`、`idempotencyKey`、`outputSchema`、`deadlineMs`、`isolation?`	原子运行一次性 Agent，返回经 JSON Schema 校验的严格 JSON
`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_wait_many`	`turnIds`、`mode?`、`waitMs?`	等待任意或全部 Turn，返回 ready 与 pending 集合
`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，可递归销毁后代并丢弃底层会话

cs_agent_run_structured 内部完成 create oneshot -> send -> wait -> cancel on deadline -> destroy，再执行严格 JSON.parse 和 JSON Schema 校验。成功返回 { "operationId": "...", "result": ... }；同一调用者用同一个 idempotencyKey 重试相同输入时，返回同一个已持久化结果。相同键用于不同 prompt、schema 或 isolation 会返回 IDEMPOTENCY_CONFLICT。deadlineMs 从原子调用开始计时，覆盖创建、发送、等待以及有界的取消/销毁收尾；命中 deadline 时会先取消 Turn，再销毁一次性 Agent。若底层收尾超过剩余预算，调用会按 deadline 返回错误，同时继续观察迟到的清理结果。解析和 schema 失败也会销毁。

isolation 只支持 inheritMcpServers、inheritEnvironment、permissionMode、 nonInteractivePermissions 和 permissionPolicy。inheritMcpServers: false 去掉用户/项目配置的 MCP，但保留受管 Agent 返回控制面的认证 loopback MCP；inheritEnvironment: false 不继承环境变量，但保留启动 ACP 命令所需的 PATH 和显式认证注入。当前不提供 filesystem 或 network 强隔离，这些字段及其他未知隔离字段会在输入校验阶段拒绝，不会静默忽略。

默认 defaultPermissions 是 approve-reads：读取类权限可以自动批准，写入等其他操作不会被静默批准。权限请求会通过等待工具返回给祖先调用者，由它调用 cs_agent_respond_permission 处理；没有可交互调用者时，默认 nonInteractivePermissions: "deny" 会拒绝该请求。

sessionOptions 支持 model、systemPrompt、allowedTools 和 maxTurns。附件使用 { "mediaType": "...", "data": "<base64>" }。cs_agent_send 的 idempotencyKey 在同一调用者范围内全局去重；重试同一任务时应复用原键，向不同 Agent 发送任务时也必须使用不同的键。兼容字段 timeoutMs 不限制 Agent 任务执行时间；调用方应通过等待、取消和 maxTurns 管理任务，而不是按预估耗时设置 Turn deadline。

maxTurns 是一个任务在 Agent 内部可使用的 agentic turns 硬上限，不是 Facade Turn 数量、超时时间或递归委派深度。普通代码实现、审查、调试和工具调用较多的任务应省略该字段，使用适配器默认行为；只有调用方需要严格预算并接受达到上限即失败时才应设置。不同适配器的支持范围和计数方式可能不同，不要根据预估任务时长自动猜测较小值。达到上限时 Turn 会保持 failed，返回 MAX_TURNS_EXCEEDED，且不会自动提高限制或重试任务。

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

多个独立任务应先完成全部 cs_agent_send，再调用 cs_agent_wait_many。mode: "any" 在至少一个 Turn ready 时返回该轮全部 ready 项；mode: "all" 通常等待全部终态，但权限请求会提前返回，避免调用方与子 Agent 死锁。权限或 timeout 中断 all 时，按 turnId 累计每轮 ready，后续 message 或 terminal 覆盖较早的 action_required，并继续等待返回的 pendingTurnIds。timeout 不取消 Turn。

等待工具单次最多等待 30 秒。单 Turn 可继续使用 cs_agent_wait_message 或 Turn revision；事件流使用 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 会话，无法恢复时会明确失败，不会静默创建一个丢失上下文的新会话。

诊断 CLI

cs-agent-mcp agents 提供只读本地排障入口，不启动 MCP stdio 服务，不连接 Broker，也不持有 Broker credential 或 loopback token。它只读取 ~/.cs-agent-mcp/mcp/facades/ 中的 snapshot/lock 以及 ~/.cs-agent-mcp/sessions/ 中已有的 runtime session record，并可同时展示多个 workspace：

cs-agent-mcp agents list
cs-agent-mcp agents list --all --json
cs-agent-mcp agents status <agent-id-or-prefix>
cs-agent-mcp agents attach <agent-id-or-prefix> --history 20
cs-agent-mcp agents top
cs-agent-mcp agents ps --all

list 默认只显示 running 实例里的非 destroyed Agent；--all 会包含 stopped/unknown 实例和 destroyed Agent。status 和 attach 的 selector 在全集解析：完整 Agent ID 可在其他 snapshot 损坏时继续匹配；前缀遇到损坏 snapshot 会 fail closed，要求使用完整 ID。

文本输出会分别标记 Agent 的 KIND 和 RUNTIME。root 是当前 MCP 客户端在 Facade 中的调用者身份，不承载受管 runtime，也不会产生可跟随的任务输出；通过 cs_agent_create 创建的 managed Agent 才会记录 Turn、工具活动和输出事件。

top（别名 ps）在交互式终端中打开实时全屏视图，每秒刷新 Agent 状态。方向键、j/k、 PageUp/PageDown、Home/End、鼠标单击和滚轮用于选择；Enter 对选中的 managed Agent 进入同屏 Attach，Esc 返回列表，/ 过滤，a 切换是否包含全部状态，r 刷新，q 或 Ctrl-C 退出。 --all 只决定初始显示范围。root 行可查看但不可 Attach；终端小于 72x12 时会显示尺寸提示。

top|ps 的 Attach 子视图按原会话顺序显示用户消息、Agent 文本、thinking、tool call 输入和 tool result 输出；每项使用 [USER]、[ASSISTANT]、[THINKING]、[TOOL CALL]、 [TOOL RESULT] 或 [TOOL ERROR] 标题区分类型，正文另起一行。mention 与媒体显示只读摘要，不输出媒体二进制。长内容按终端宽度换行，向上滚动会暂停自动跟随并按新增消息数累计未读数， End 恢复实时跟随。persistent Agent 读取固定 session record；oneshot Agent 按时间合并同一 Agent 已有的原生 task session records。历史 session 不存在时显示 conversation unavailable 和已有错误，不会无限显示 loading。会话内容不为 TUI 新建历史副本，也不启动 Agent。top|ps 要求 stdin/stdout 都是 TTY；重定向或脚本场景应使用 list --json 或 attach --json，不会输出 ANSI 控制序列。

独立的 agents attach 命令保持事件流接口：先输出目标 Agent 的当前 snapshot 和有限历史，再按 cursor 只读跟随新事件。它不会发送消息、响应权限、取消 Turn 或修改任何状态；Agent destroyed 时返回 0，实例 stopped/unknown 或 generation 更替时在最终 drain 后返回非零，Ctrl-C 返回 0。

JSON 输出使用 cs-agent-mcp.diagnostics.v1。attach --json 是 JSONL，每行只会是 snapshot、event 或 terminal。事件投影只暴露 allowlist 字段：output stream 的文本、有界工具摘要、状态和终态错误摘要。thought 文本、identity、完整 Message、Permission request、 raw tool payload、rawInput、rawOutput 和其他未知字段不会输出。

故障排查

现象	检查方式
安装到的版本不符合预期	运行 `npm view cs-agent-mcp version` 和 `cs-agent-mcp --version`，然后重新安装 `cs-agent-mcp@latest`
根 Agent 看不到 MCP	运行 `codex mcp list` 或 `claude mcp list`，确认存在 `cs-agent`，然后新开客户端会话
Codex 或 Claude 探测失败	先运行 `codex --version` 或 `claude --version`，确认对应 CLI 已安装并登录，再调用 `cs_agent_capabilities` 探测
第一次调用较慢	等待 npm 下载对应 ACP 适配器及 SDK；网络失败后可以重试，不需要单独安装适配器
手工启动后没有终端提示	这是正常行为；`cs-agent-mcp` 使用 stdin/stdout 传输 MCP 协议，不提供交互式界面
不知道哪个 Agent 卡住	在终端运行 `cs-agent-mcp agents top` 实时浏览，或用 `agents list --all` 后接 `agents status <agent-id>`
想阅读某个 Agent 的完整会话	运行 `cs-agent-mcp agents top` 后选择 managed Agent 并按 Enter；消息、thinking 和工具调用均只读显示
想跟随某个 Agent 的原始事件	运行 `cs-agent-mcp agents attach <agent-id>`；这是只读事件流，不会响应权限或取消任务
Broker 版本不兼容	关闭使用旧 Broker 的全部 MCP 根客户端后重试；活跃旧 Broker 不会被新前端强制终止
`cwd` 或 workspace root 被拒绝	确认目录真实存在，并且位于 MCP 客户端声明的 workspace roots 内

稳定性与反馈

项目当前处于 0.x 阶段。工具名、输入字段、结构化输出和持久化 schema 属于公开契约；升级前请查看更新日志。发现安装、兼容性或运行问题时，请通过 GitHub Issues 反馈。

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