用 MCP 把 Claude Managed Agents 变成聊天工具cma-mcp 服务器搭建、扩展与排障全指南【免费下载链接】claude-cookbooksA collection of notebooks/recipes showcasing some fun and effective ways of using Claude.项目地址: https://gitcode.com/GitHub_Trending/an/claude-cookbooks本指南以仓库中managed_agents/cma-mcp模块为核心讲解如何把一个薄薄的 MCP 服务器封装在 Claude Managed AgentsCMASessions API 之上让 Claude Desktop 或 claude.ai Web 都能像调用普通工具一样直接启动并对话组织内托管的 Agent。读完你会掌握stdio 与 Streamable HTTP 两种传输方式的完整落地步骤、九个工具的注册机制、如何用几行代码扩展新工具以及最常见的部署与排障清单。该模块的入口指导文档 CLAUDE.md 把运维要点浓缩成三条规则本文将其展开并与源码逐一对照。一、模块定位一个工具集、两个入口、九个工具cma-mcp是一个把 Managed Agents 会话原语暴露为 MCP 工具的服务器其核心设计一句话可以概括一套共享工具集两个入口文件——src/server.ts 走 stdio 协议给 Claude Desktop 本地拉起子进程用src/server-http.ts 走 Streamable HTTP供 claude.ai Web 以自定义 Connector 方式远程接入。各文件的职责划分非常清晰见 README.md文件职责src/cma.ts对 Anthropic SDK 的封装调用两种传输方式共享src/tools.ts九个server.tool(...)注册两种传输方式共享src/server.tsstdio 入口约 10 行src/server-http.tsHTTP 入口 Bearer 鉴权约 40 行DockerfileHTTP 路径在 Fly / Railway / Render 上的部署镜像依赖方面package.json 显示它需要anthropic-ai/sdk 0.95.1、modelcontextprotocol/sdk ^1.22.0与zod脚本只保留三个核心命令bun run stdio、bun run http和bun run typecheck。二、先建立心智模型谁是前端谁是后端2.1 对话中继模型skill.md给出了最关键的思维模型你在 Claude Desktop 里打字面对的那个 Claude只是一个中继relay。它的调用序列是send_message把你的话原样送入 CMA 会话wait_for_idle阻塞等待直到远端 Agent 结束当前回合把 Agent 的回复展示给你。真正的工具调用、代码执行、仓库修改都发生在CMA 会话里而不是 Desktop 本地。整个数据流见 README.md 的图示User ─▶ Claude ─▶ MCP: send_message wait_for_idle ─▶ CMA session ─▶ stream-to-idle ─▶ reply。2.2 八个 1:1 封装 一个编造动词九把工具里有八把是 CMA 端点的直线包装工具名与端点一一对应下表来自 README.md工具CMA 端点list_agents/get_agentGET /v1/agents[/{id}]create_sessionPOST /v1/sessionssend_message/interruptPOST /v1/sessions/{id}/eventsget_sessionGET /v1/sessions/{id}list_eventsGET /v1/sessions/{id}/eventsarchive_sessionPOST /v1/sessions/{id}/archivewait_for_idle流式读取…/events/stream直到 idle返回回复文本唯一的“编辑”是wait_for_idle因为 MCP 是请求/响应模型而 CMA 的完成通知是SSE 流式的所以必须有一个工具负责在单次工具调用内部“把流等到空闲再返回”。从 cma.ts 可以看到它的实现订阅events.stream遇到agent.message时拼接文本块到reply遇到agent.tool_use/agent.mcp_tool_use时把→ 工具名记入activity直到收到session.status_idle或session.status_terminated才跳出默认超时timeout_sec 120兜底返回状态idle | terminated | timeout | requires_action。代码注释明确写着“This is the SSE→request/response shim MCP needs — the only place we editorialize over the raw API.”2.3 无状态服务器session_id是唯一的会话状态create_session返回session_id后由 Claude 在每一轮后续调用中把它透传下去MCP 服务器本身不保存任何状态。这也解释了为什么 HTTP 入口刻意采用无状态模式stateless不配sessionIdGenerator每次 HTTP 请求都新建一个McpServer transport 实例即可因为工具本身无状态CMA 的session_id由调用方 Claude 负责跨轮持有。见 server-http.ts 的注释与实现。2.4 两种传输同一套工具tools.ts 里的registerTools(server)是唯一注册点stdio 与 HTTP 入口都调用它随后各自接入自己的 transport。二选一即可无需重复维护。三、路径一Claude Desktop 本地接入stdio适用对象是 Claude Desktop / Claude Code——它们能本地拉起子进程所以走 stdio浏览器里的 claude.ai 无法派生本地进程请走下一节的 HTTP 路径。3.1 一次性环境准备会话必须指定environment_id用antCLI 创建一次即可注意--transform id -r直接取回环境 ID 供复制ant beta:environments create --name cma-mcp \ --config {type: cloud, networking: {type: unrestricted}} --transform id -rAgent 不需要这个服务器来创建——它只驱动工作区里已经存在的 Agent。创建或更新 Agent 请用antCLI 或 Console 完成这也是 skill.md 强调的边界。3.2 环境变量与 .env.local服务器在启动时就会校验环境变量。从 cma.ts 的源码可见CLAUDE_ENVIRONMENT_ID缺失会直接throw new Error(CLAUDE_ENVIRONMENT_ID is required)因此本地运行前需要准备ANTHROPIC_API_KEYsk-ant-... CLAUDE_ENVIRONMENT_IDenv_...3.3 注册进 Claude Desktop把下面的配置块写入 macOS 的~/Library/Application Support/Claude/claude_desktop_config.json并重启 Desktop{ mcpServers: { cma: { command: bun, args: [run, /absolute/path/to/managed_agents/cma-mcp/src/server.ts], env: { ANTHROPIC_API_KEY: sk-ant-..., CLAUDE_ENVIRONMENT_ID: env_... } } } }这里必须写bun的绝对路径且 env 必须内联在配置里——stdio 服务器不会读取你 shell 的环境变量。排障表里对应症状“CLAUDE_ENVIRONMENT_ID is required”的检查项正是“Desktop 配置里缺 env 块”。3.4 端到端验证在新开一个 Desktop 对话里直接提问list my managed agents, start a session with the first one, and relay this message to it: hello.如果配置正确你会看到工具调用依次执行list_agents→create_session→send_message→wait_for_idle并最终返回 Agent 的回复。四、路径二claude.ai Web 远程接入Streamable HTTP同一套工具但服务器跑在公网 URL 上claude.ai 以“自定义 Connector”身份连进来。这条路径适合给无密钥的非技术用户开放能力但代价是URL 一旦公开Bearer token 就是访问你ANTHROPIC_API_KEY的 CMA 额度的唯一闸门见 skill.md 的 Gotchas。因此不配 token 绝不部署、token 绝不写日志、要像 API key 一样定期轮换。4.1 生成令牌并本地验证export CMA_MCP_TOKEN$(openssl rand -hex 32) bun run http # → 监听 :3000/mcp本地联调可用 ngrok / cloudflared 获得临时公网 URL。先在本地验证鉴权与路由从 server-http.ts 可以看到完整逻辑——/health返回ok非/mcp路径返回 404而/mcp请求用timingSafeEqual做常量时间比较的 Bearer 鉴权失败即返回 401CMA_MCP_TOKEN缺失时服务器启动即抛错。本地出现 401先检查你是否在启动bun run http的那个 shell里导出过 token。4.2 部署仓库自带的 Dockerfile 以oven/bun:1-slim为基础镜像、默认监听PORT3000、启动命令为bun run src/server-http.ts可直接推到 Fly / Railway / Render。需要设置三个 secretsANTHROPIC_API_KEY、CLAUDE_ENVIRONMENT_ID、CMA_MCP_TOKEN。也支持 Cloudflare Workers因为 transport 用的是WebStandardStreamableHTTPServerTransport天生 fetch 原生。迁移方式是把process.env换成入参env、Bun.serve换成export default { fetch }即可server-http.ts 的代码是 Web 标准 Request/Response作者注释说明同一文件可跑在 Bun、Node 18、Deno 上。4.3 在 claude.ai 添加自定义 Connectorclaude.ai → Settings → Connectors → Add custom connector按表填写FieldValueNameCMAURLhttps://your-deploy/mcpAuthenticationBearer token → 你的CMA_MCP_TOKENTeam / Enterprise 组织注意按 URL 添加 Connector 通常是org-admin 专属权限——普通用户看到的是精选目录而非 URL 输入框。正确姿势是管理员在组织设置里添加一次 URL token然后每个成员的 Connectors 列表里就会出现可启用的项。这恰好也正是面向非技术用户规模化推广时想要的形态。4.4 验证新开对话 → 启用CMAConnector → 使用与 stdio 路径相同的验证 prompt 即可。五、中继模式把 Project 指令写清楚如果不对 Claude 加以引导Desktop 里的 Claude 会倾向于自己作答而不是当中继。仓库给出的推荐做法是把下面这段话放入 Project 的自定义指令custom instructions中见 skill.mdYou are a frontend for a backend Managed Agent reached via thecmaMCP tools. On the first user turn:list_agents(if needed) →create_session→send_message(user text verbatim)→wait_for_idle→ return thereplyverbatim. On subsequent turns:send_message→wait_for_idle. Do not answer from your own knowledge; do not paraphrase the backends reply. Ifwait_for_idlereturnsstatus: timeout, tell the user its still running and offer to keep waiting.要点消息逐字透传verbatim、回复逐字返回、不得用自己的知识作答、不得转述改写。当wait_for_idle返回status: timeout时要告知用户任务仍在运行并主动提出继续等待。六、如何新增工具三层原则与“故意不暴露”清单CLAUDE.md 给出了扩展新工具的固定套路先在src/cma.ts里 1:1 映射 CMA 端点再到src/server.ts里用 zod schema 注册。实际代码中注册点统一收敛在 tools.ts 的registerTools所以完整链路是三步在 cma.ts 编写 SDK 调用函数例如createSession封装anthropic.beta.sessions.create在 tools.ts 用server.tool(name, description, zodSchema, handler)注册并顺手给参数写describe说明与范围约束两个入口文件无需改动——因为它们共享registerTools工具会自动同时出现在 stdio 与 HTTP 两套传输里。以list_agents为例可以看到 schema 的规范写法limit限定1..200默认 50、name_contains做大小写不敏感的子串过滤而wait_for_idle的timeout_sec限定5..600默认 120。这些约束都来自 tools.ts 的 zod 定义能有效防止越界参数打到上游 API。6.1 为什么有些端点故意不暴露不是所有 CMA 能力都值得暴露成聊天工具。skill.md 用一张表明确标注了刻意不暴露的端点及理由这份取舍本身就是一种安全设计Endpoint不暴露的理由agents.archive永久操作、无法撤销——一次错误的工具调用可能毁掉生产环境的 Agentagents.create/updateAgent 创作属于antCLI / Console 的职责不该发生在对话回合里sessions.delete、environments.*属于破坏性基础设施操作vaults.*、credentials.*敏感凭据sessions.resources.add需要聊天用户不可能持有的 token / 文件 ID当然这些并非绝对禁区——skill.md同时说明如果你的场景确实需要在src/cma.tssrc/server.ts实为tools.ts里补上也只是几行代码的事。七、长回合与工具超时的对抗策略wait_for_idle是阻塞式调用。当 CMA Agent 运行数分钟大仓库克隆、大量工具调用时MCP 客户端可能先于它超时。仓库给出两种缓解手段skill.md传更小的timeout_sec并循环轮询wait_for_idle超时会返回status: timeout与last_event_id用同一个session_id再次调用即可续等改为轮询模式让 Claude 用get_sessionlist_events(after_id...)增量拉取事件不依赖单次阻塞调用。第二种方式之所以可行得益于 cma.ts 的listEvents对after_id的增量语义流式遍历事件找到等于after_id的那条之前全部跳过之后的事件才收集——配合summarizeEvent把事件压成{id, type, processed_at, text/name/is_error/stop_reason}的精简结构避免把整棵对象树塞进 MCP 响应。八、计费归属与安全边界skill.md特别提醒了计费模型所有 CMA 用量都记在服务器配置里那个ANTHROPIC_API_KEY名下而不是 Desktop 用户的账户。这正是该设计的价值所在——非技术用户无需持有任何密钥——但反过来要求你按该 key 的工作区额度上限来规划用量别让单用户的长时间会话把共享额度耗尽。九、调试排障速查表CLAUDE.md 把调试场景浓缩为“读 skill.md → 走对应路径检查清单”skill.md 则给出可直接对照的症状表症状检查方向Desktop 里看不到cma工具配置文件路径写错或 Desktop 进程的 PATH 里没有bun改用bun绝对路径查看 Desktop 的 MCP 日志报错CLAUDE_ENVIRONMENT_ID is requiredDesktop 配置里缺 env 块——stdio 服务器不读 shell 环境变量wait_for_idle返回空的replyAgent 空闲时没有产生文本例如只做了工具调用用list_events查看完整日志每轮对话都新建会话Claude 没有透传session_id需要收紧 Project 指令claude.ai Connector 显示 “couldnt connect”URL 错误、服务器不可达或 token 不匹配查服务器日志里的 401HTTP 服务器本地返回 401启动bun run http的那个 shell 里没有导出CMA_MCP_TOKEN十、快速起步与常用命令模块内快速体验来自 README.mdcd managed_agents/cma-mcp bun install claude之后直接对 Claude 说walk me through setting this up.——Claude 会读取 skill.md先问你目标客户端Claude Desktop → stdio 路径claude.ai Web → HTTP 部署 Connector再沿着对应路径的清单逐步驱动。两条路径最终收敛到同一个send_message → wait_for_idle循环和中继模式 Project 指令。常用命令汇总package.json命令作用bun install安装依赖bun run stdio以 stdio 方式启动Claude Desktopbun run http以 Streamable HTTP 方式启动claude.ai监听:3000/mcpbun run typecheck运行tsc --noEmit做类型检查最后回到 CLAUDE.md 强调的三条运维铁律它们贯穿本模块的全部工作流接入前先查/claude-api技能确认 Managed Agents 的完整 API 参考别靠猜字段名部署与排障时先读 skill.md 并按客户端选路径扩展工具时坚持端点 1:1 映射并尊重“故意不暴露”清单。把握住“无状态服务器 session_id透传 wait_for_idle流转请求”这三点你就掌握了 cma-mcp 的全部设计精髓也就能把同样的模式复用到任何 SSE 式 Agent 后端上。【免费下载链接】claude-cookbooksA collection of notebooks/recipes showcasing some fun and effective ways of using Claude.项目地址: https://gitcode.com/GitHub_Trending/an/claude-cookbooks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考