企业官网建设流程全解析

如何用 MCP Server 把 Claude Managed Agents 接入 Claude Desktop 与 claude.ai？

【免费下载链接】claude-cookbooksA collection of notebooks/recipes showcasing some fun and effective ways of using Claude.项目地址: https://gitcode.com/GitHub_Trending/an/claude-cookbooks

claude-cookbooks 仓库中的 cma-mcp 是一个薄 MCP（Model Context Protocol）Server，它把 Claude Managed Agents（CMA）的 Sessions API 封装成 9 个 MCP 工具，让你可以在Claude Desktop或claude.ai 网页版中直接启动、对话你所在 workspace 里已托管的 Managed Agent——就像调用本地工具一样。本文按两条路径走一遍完整接入流程：Desktop 走 stdio（本地进程），claude.ai 网页走 Streamable HTTP（部署后的公开 URL + Bearer token）。两条路径共用同一套工具定义，区别只在你使用的客户端。

准备工作：两条路径共用

在开始任何一条路径之前，先完成这些一次性准备：

1. 安装依赖。进入 cma-mcp 目录并用 Bun 安装：

   cd managed_agents/cma-mcp bun install

   依赖版本见 package.json：@anthropic-ai/sdk要求^0.95.1（README 中说明需 ≥ 0.95.1），以及@modelcontextprotocol/sdk和zod。

2. 创建 CMA environment（一次性，session 需要environment_id）：

   ant beta:environments create --name cma-mcp \ --config '{type: cloud, networking: {type: unrestricted}}' --transform id -r

   执行后得到一个env_开头的 ID，记下来，两条路径都会用到。

3. 准备一个 API key（sk-ant-开头）和一个已存在的 Managed Agent。注意：这个 MCP Server不创建 agent，它只驱动你 workspace 里已经存在的 agent；agent 的创建和更新要通过antCLI 或 Console 完成。

4. 在项目根目录建.env.local，写入两个值（sk-ant-...与env_...换成你自己的真实值）：

   ANTHROPIC_API_KEY=sk-ant-... CLAUDE_ENVIRONMENT_ID=env_...

   这两个值在两条路径中都是必需的：stdio 路径下 Desktop 的子进程不读你的 shell 环境变量，必须在 Desktop 配置里显式传入（见下文）；HTTP 路径下则作为部署 secrets 传入。

路径一：接入 Claude Desktop（stdio，本地）

这条路径下，Claude Desktop 会把 MCP Server 作为子进程用 stdio 拉起，入口是 src/server.ts。

1. 注册到 Claude Desktop。编辑~/Library/Application Support/Claude/claude_desktop_config.json（macOS 路径），加入如下配置，然后重启 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_..." } } } }

   其中args里的路径必须替换成你本机上src/server.ts的绝对路径；env块必须完整填写——stdio server 读不到你 shell 里的环境变量，漏掉CLAUDE_ENVIRONMENT_ID会报CLAUDE_ENVIRONMENT_ID is required。

2. 测试。在 Desktop 新开一个对话，输入：

   list my managed agents, start a session with the first one, and relay this message to it: hello.

   预期行为是 Claude 依次调用list_agents→create_session→send_message→wait_for_idle，然后把 CMA agent 的回复原样带回。如果你看到 CMA session 的回复内容出现在 Desktop 对话中，说明接入成功。

3. （推荐）配置 relay 模式的 Project instructions。没有引导时，Desktop 里的 Claude 会试图自己回答，而不是转发给后端 agent。在 Project 的 custom instructions 中放入：

   You 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 backend's reply. Ifwait_for_idlereturnsstatus: "timeout", tell the user it's still running and offer to keep waiting.

路径二：接入 claude.ai 网页版（Streamable HTTP，远程）

浏览器里的 claude.ai 无法启动本地进程，所以 stdio 只适用于 Desktop / Claude Code；claude.ai 走 HTTP 路径，入口是 src/server-http.ts。工具集完全相同，但服务运行在一个公开 URL 上，claude.ai 以自定义 Connector 方式连接。

1. 生成访问 token，并妥善保管——持有这个 token 的人可以驱动你的 agent：

   export CMA_MCP_TOKEN=$(openssl rand -hex 32)

2. 本地先跑一遍（测试时可用 ngrok / cloudflared 获得公开 URL）：

   bun run http # → :3000/mcp

   服务监听:3000/mcp。src/server-http.ts中 token 是强制的：未设置CMA_MCP_TOKEN时进程直接抛错退出。

3. 部署。Dockerfile 面向 Fly / Railway / Render 部署 HTTP 路径（基于oven/bun:1-slim，EXPOSE 3000）；把ANTHROPIC_API_KEY、CLAUDE_ENVIRONMENT_ID、CMA_MCP_TOKEN三个值配置为部署平台的 secrets。（Cloudflare Workers 也可行——WebStandardStreamableHTTPServerTransport是 fetch 原生的，把process.env换成env、Bun.serve换成export default { fetch }即可。）

4. 在 claude.ai 添加自定义 Connector：Settings → Connectors → Add custom connector，字段如下：

   Field	Value
   Name	CMA
   URL	https://<your-deploy>/mcp
   Authentication	Bearer token → 你的CMA_MCP_TOKEN

   URL 中的<your-deploy>替换为你实际部署得到的域名。注意：Team / Enterprise 组织里，通过 URL 添加 Connector 通常只有组织管理员能做——普通成员看到的是精选目录而非 URL 输入框。由管理员在 org 设置里加一次 URL + token，之后每位成员的 Connectors 列表里都会出现该 Connector 供启用。

5. 验证。先确认服务可达：GET /health返回ok（Bearer 鉴权只作用于/mcp路径）。然后在 claude.ai 新开对话，启用CMAconnector，使用与 Desktop 相同的测试提问（上一步的 "list my managed agents…"）。

九个工具与调用循环

这套接入暴露的工具（注册逻辑见 src/tools.ts）：

前八个是 CMA endpoint 的一对一封装；wait_for_idle是唯一一个"编辑器加工"——因为 MCP 是请求/响应模型，而 CMA 的完成事件是 SSE 流，必须在一次工具调用内部把流"阻塞到 idle"。典型循环是每轮send_message→wait_for_idle。session_id是唯一的会话状态：由create_session返回，由 Claude 在后续每轮调用中传递；MCP Server 本身无状态。

wait_for_idle的timeout_sec参数范围 5–600，默认 120。

排查与限制

另外三个需要知道的边界（来自 skill.md）：

• 长回合会撞上工具超时。wait_for_idle是阻塞的；如果 CMA agent 跑了好几分钟（大仓库 clone、大量工具调用），MCP 客户端可能超时。两种缓解方式：传更小的timeout_sec然后循环调用（wait_for_idle超时时返回status: "timeout"+last_event_id，可再次调用），或让 Claude 改轮询get_session+list_events(after_id=...)。
• 计费归属。所有 CMA 用量都计在 server 配置里那个ANTHROPIC_API_KEY上，而不是 Desktop 用户自己的账号——这正是给非技术用户提供服务的用途，所以该 key 所在 workspace 的额度要按实际用量规划。
• 安全模型（HTTP 路径）。URL 是公开的，bearer token 是ANTHROPIC_API_KEYCMA 配额前面唯一的闸门。不要不带 token 部署，不要把 token 打进日志，按普通 API key 一样轮换。
• 刻意未暴露的 endpoint。agents.archive（永久且不可撤销）、agents.create/update（agent 的编写应在antCLI / Console 做）、sessions.delete、environments.*（破坏性基础设施操作）、vaults.*/credentials.*（密钥）、sessions.resources.add。如果确有需求，按 skill.md 的说法，在src/cma.ts+src/server.ts里加几行即可。

参考位置

• README：Quickstart 与工具表
• skill.md：两条路径的完整 checklist、relay 模式指令与调试表
• src/server.ts（stdio 入口）与 src/server-http.ts（HTTP 入口 + bearer 鉴权）
• package.json：bun run stdio、bun run http、bun run typecheck三个脚本；Dockerfile：部署镜像

【免费下载链接】claude-cookbooksA collection of notebooks/recipes showcasing some fun and effective ways of using Claude.项目地址: https://gitcode.com/GitHub_Trending/an/claude-cookbooks