SDK 中的 MCP

配置本地或远程 MCP、筛选工具，并理解会话禁用服务器的生效时机。

This page has not been translated into English yet. The original Chinese version is shown below.

SDK 可以为会话接入 MCP 工具。服务器既可以是 runtime 启动的本地进程，也可以是通过 HTTP 或 SSE 访问的远程服务。这里使用 SDK 的 mcpServers 配置，不直接套用云端代理仓库设置的必填字段规则。

配置本地与远程服务器

以下是创建会话的配置片段，假定 client 已初始化，本地 mcp-server.js 已由应用提供：

const session = await client.createSession({
  mcpServers: {
    "local-tools": {
      type: "local",
      command: "node",
      args: ["./mcp-server.js"],
      cwd: "./servers",
      env: { DEBUG: "true" },
      tools: ["*"],
      timeout: 30000,
    },
    github: {
      type: "http",
      url: "https://api.githubcopilot.com/mcp/",
      tools: ["*"],
    },
  },
});

远程服务需要认证时，通过 headers 提供相应请求头；上例只展示连接位置，不包含可用凭据。官方示例中的 Bearer ${TOKEN} 是示例字符串，本页不据此假定 SDK 会替应用读取或展开环境变量。

字段	本地服务器	远程服务器
`type`	`local` 或 `stdio`，可省略，默认 local	必填，`http` 或 `sse`
启动或地址	`command`、`args` 必填	`url` 必填
运行环境	可选 `env`、`cwd`	可选 `headers`
工具	可选 `tools`	可选 `tools`
超时	可选 `timeout`，毫秒	可选 `timeout`，毫秒

30000 是示例超时，不是本页确认的默认值。工具调用的权限响应另见工具交互事件，声明工具可见不等于所有操作都应自动批准。

用 tools 限定工具集合

tools: ["*"] 允许该服务器全部工具；指定名称数组只暴露列出的工具；tools: [] 不暴露任何工具。这里没有另一套 allow 或 disallow 字段。需要稳定集合时显式填写，不从字段可选推断省略后的默认行为。

工具名称筛选与关闭服务器不同：空工具数组表达工具不可用，不能替代下面的服务器禁用选项。

为单个会话禁用服务器

在创建或恢复请求上设置 disabledMcpServers，值是要禁用的服务器名称，必须精确匹配。例如 disabledMcpServers: ["github"] 针对名为 github 的配置生效。

新建会话或冷恢复时，禁用的服务器不会启动，runtime 也不会发起它的认证。
恢复仍驻留在 runtime 中的会话，不能用此选项撤销已经启动的服务器。
设置只作用于本次创建或恢复的会话配置，不改全局 MCP 设置，也不删除服务器定义。

不同语言名称分别是 Node.js disabledMcpServers、Python disabled_mcp_servers、Go DisabledMCPServers、.NET DisabledMcpServers、Java setDisabledMcpServers(...)、Rust with_disabled_mcp_servers(...)。

排查没有工具或连接失败

先检查本地命令与参数能否启动服务器、进程是否立即退出，以及 stderr 中的错误；再检查 tools 是否意外为空或名称不匹配。远程连接检查 URL、服务运行情况和认证头。超时先区分服务慢与地址不可达，再考虑调整 timeout。

工具已出现但未被调用时，还要检查任务是否确实需要该工具。连接成功与模型选择工具是不同阶段；不要仅凭一次未调用就认定 MCP 配置无效。