@anthropic-ai/claude-agent-sdk 接 MCP：配置与连接验证

我家大橘 技术创作者 2026-11-03 23 阅读

Anthropic 的官方仓库 README 里写着一句关键变更：Claude Code SDK 已经改名为 Claude Agent SDK，安装包也换成 @anthropic-ai/claude-agent-sdk（命令：npm install @anthropic-ai/claude-agent-sdk）。这意味着网上大量写着 claude-code-sdk 的旧教程在配置字段名上已经对不上号，而 MCP（Model Context Protocol，一种让模型调用外部工具的开放协议）接入方式在新 SDK 文档里被重新整理过。下面按”写配置 → 放权限 → 看状态”这三段给出可执行路径。

下文凡标注【官方】的出自 Anthropic 官方文档与仓库原文，标注【社区】的出自第三方仓库实践，其余为按官方口径所作的推算。

开始前的三个前置条件

1. 装好 SDK 并确认包名。 在项目目录执行：

npm install @anthropic-ai/claude-agent-sdk

然后打开 package.json，确认 dependencies 里出现 @anthropic-ai/claude-agent-sdk。旧项目里若还留着 claude-code-sdk，先按官方仓库 README 提到的迁移指南处理：【官方】”The Claude Code SDK is now the Claude Agent SDK. Please check out the migration guide for details on breaking changes.”

2. 准备一个能连上的 MCP 服务器。 两种形态二选一：本地进程用 stdio 启动（需要 command 与 args），远程服务用 HTTP（需要 type: "http" 与 url）。走 GitHub 这类需要鉴权的服务，还要先备好凭据——【官方】文档的 GitHub 示例要求创建带 repo 权限的个人访问令牌（PAT）并导出为环境变量：

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

3. 准备模型调用凭据。 官方 README 未在本页列出环境变量清单。【经验判断】按 Claude Code / Agent SDK 的通行做法，设置 ANTHROPIC_API_KEY；若你用订阅账号登录则无需设置这一项。

配置写在哪里：三个位置的区别

MCP 服务器配置有三种落法，容易混。这是官方文档与社区实践对照后的选择表：

落法 谁读取它 生效条件 适合谁
代码内 options.mcpServers 你自己的 SDK 调用 每次 query() 传入 硬编码或动态生成服务器列表
项目根目录 .mcp.json Agent SDK 的 project 配置源 【社区】默认 query() options 下即被读取 多 Agent 共享同一份配置
复用 Claude Code 的 .mcp.json 两者共用同一文件 【社区】同一文件在 Claude Code 里也生效 已经在用 Claude Code 的团队

【官方】MCP 指南给出的内联写法是 mcpServers 配合 allowedTools 两个字段：

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "...",
  options: {
    mcpServers: {
      github: { type: "http", url: "https://api.githubcopilot.com/mcp/" },
    },
    allowedTools: ["mcp__github__*"],
  },
})) {
}

【官方】还给出过 stdio 形态的字段写法：command 加 args。所以”远程 HTTP”和”本地启动进程”是两套字段，不要把 command 和 url 混写进同一个服务器对象里——这是最常见的”配置看起来对、但连不上”的原因。

容易漏掉的一步：allowedTools 与工具命名规则

【官方】文档明确说明，MCP 工具需要显式允许后才能被调用；【官方】另一处示例则写明，在 permissionMode: "acceptEdits" 下不需要 allowedTools。这两句话不矛盾，区别在于权限模式。

工具命名规则是 mcp__<服务器>__<工具>。【社区】的第三方集成示例把它讲得最直白：不给 allowedTools 时，Claude 能看见这些工具但不能调用；写 mcp__satohub__onchain_agent_preflight 只放行 Preflight 这一个工具，不会连带放行其它。

所以调试时先想清楚两件事：服务器名（你在 mcpServers 里的 key，比如 github）和工具名（服务器自己定义的名字）。工具全名 = mcp__github__<工具名>，服务器名写错一个字母，工具就永远匹配不上。

怎么确认真的连上了：看 init 消息

不要靠”跑一次看看有没有报错”来判断连接状态。【官方】文档给出的验证办法是监听初始化消息：message.type === "system" 且 message.subtype === "init" 时，message.mcp_servers 里就是各服务器及其状态。

for await (const message of query({ prompt: "...", options })) {
  if (message.type === "system" && message.subtype === "init") {
    console.log("Available MCP tools:", message.mcp_servers);
  }
}

状态字段有三种取值，含义不同：

状态 含义 该做什么
connected 已连上且鉴权通过 【官方】文档在 GitHub 示例中把”状态显示 connected”作为令牌有效的判据
pending 服务器尚未缓存工具列表 【官方】连接可能在首次工具调用时才真正建立，先触发一次调用再回看状态
failed 连接或鉴权失败 【官方】此时不要信任后续结果，先排查凭据与字段写法

pending 特别容易被误读成”没连上”。文档的说法是：服务器没有缓存工具列表时状态会显示为 pending，而连接是在第一次调用工具时建立。也就是说，看到 pending 先别改配置，先让 Agent 真的调一次那个工具。

四个真实卡点与对应解法

卡点一：状态是 failed，提示工具调用失败。 先看鉴权。GitHub 场景下【官方】示例要求 PAT 带 repo 权限，且已 export GITHUB_TOKEN=...。解法：确认变量在运行 Agent 的那个终端里已生效，重新导出后再启动进程；跨终端或 CI 里变量不继承是高频原因。

卡点二：能看见工具名，但 Agent 从不调用。 这是 allowedTools 漏配，或写成了 mcp__github 而非 mcp__github__*。解法：先用 mcp__<服务器>__* 通配放行确认通路，再逐个收紧到具体工具名。

卡点三：init 消息里根本没有这台服务器。 说明配置没被读到。核对两点：一是 .mcp.json 是否在项目根目录而非 src/ 下；二是【社区】提示的启用条件——项目根目录的 .mcp.json 需在 project 配置源启用时才会被拾取，而【社区】称默认 query() options 已包含它。

卡点四：stdio 服务器报连接失败。 多数是相对路径问题：args 里的路径相对于进程工作目录解析。解法：把 command 写成绝对路径，或让 args 里用绝对路径。

成功标志清单

一轮下来，输出里应该同时出现这几样：init 消息的 mcp_servers 中该服务器条目状态为 connected（或在首次调用后由 pending 转 connected）；Agent 的回复中确实包含外部工具返回的真实数据；allowedTools 里写的工具全名与实际调用名完全一致。

再补一个容易忽略的验收点：把配置从代码内联挪到 .mcp.json 后要重跑一遍 init 检查，确认两种落法都生效，再删掉其中一个——否则你不知道刚才成功的是哪一份配置。

延伸入口与迁移提醒

【官方】README 里的 “Learn more in the official documentation” 指向 Anthropic 官方文档，Agent SDK 的 MCP 专页是 platform.claude.com/docs/en/agent-sdk/mcp（该文档站提供多语言版本，抓取时可见法语页与德语页）。

最后提醒一句版本分界：本文所有字段名以 @anthropic-ai/claude-agent-sdk 为准；仍在用 claude-code-sdk 的项目，先走官方迁移指南，再按上面的路径配 MCP，否则你会拿着旧字段名去查新文档，越查越乱。

参考来源

# AI# 知识

评论区

0 条评论

登录后可评论。

我家大橘 23 阅读