MCP 连接器

Claude 的模型上下文协议（MCP）连接器功能使您能够直接从 Messages API 连接到远程 MCP 服务器，无需单独的 MCP 客户端。

当前版本：此功能需要 beta 请求头："anthropic-beta": "mcp-client-2025-11-20"

之前的版本（mcp-client-2025-04-04）已弃用。请参阅下方的已弃用版本文档。

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

主要功能

直接 API 集成：无需实现 MCP 客户端即可连接到 MCP 服务器
工具调用支持：通过 Messages API 访问 MCP 工具
灵活的工具配置：启用所有工具、允许特定工具或禁止不需要的工具
按工具配置：使用自定义设置配置单个工具
OAuth 身份验证：支持用于已验证服务器的 OAuth Bearer 令牌
多服务器：在单个请求中连接到多个 MCP 服务器

限制

在 MCP 规范的功能集中，目前仅支持工具调用。
服务器必须通过 HTTP 公开暴露（支持 Streamable HTTP 和 SSE 传输）。本地 STDIO 服务器无法直接连接。
MCP 连接器目前不支持 Amazon Bedrock 和 Google Vertex。

在 Messages API 中使用 MCP 连接器

MCP 连接器使用两个组件：

MCP 服务器定义（mcp_servers 数组）：定义服务器连接详情（URL、身份验证）
MCP 工具集（tools 数组）：配置要启用哪些工具以及如何配置它们

基本示例

此示例使用默认配置启用 MCP 服务器中的所有工具：

MCP 服务器配置

mcp_servers 数组中的每个 MCP 服务器定义连接详情：

{
  "type": "url",
  "url": "https://example-server.modelcontextprotocol.io/sse",
  "name": "example-mcp",
  "authorization_token": "YOUR_TOKEN"
}

字段说明

属性	类型	必填	说明
`type`	string	是	目前仅支持 "url"
`url`	string	是	MCP 服务器的 URL。必须以 https:// 开头
`name`	string	是	此 MCP 服务器的唯一标识符。必须由 `tools` 数组中的恰好一个 MCPToolset 引用。
`authorization_token`	string	否	如果 MCP 服务器需要，则提供 OAuth 授权令牌。参见 MCP 规范。

MCP 工具集配置

MCPToolset 位于 tools 数组中，配置来自 MCP 服务器的哪些工具被启用以及如何配置它们。

基本结构

{
  "type": "mcp_toolset",
  "mcp_server_name": "example-mcp",
  "default_config": {
    "enabled": true,
    "defer_loading": false
  },
  "configs": {
    "specific_tool_name": {
      "enabled": true,
      "defer_loading": true
    }
  }
}

字段说明

属性	类型	必填	说明
`type`	string	是	必须为 "mcp_toolset"
`mcp_server_name`	string	是	必须与 `mcp_servers` 数组中定义的服务器名称匹配
`default_config`	object	否	应用于此集合中所有工具的默认配置。`configs` 中的单个工具配置将覆盖这些默认值。
`configs`	object	否	按工具配置覆盖。键为工具名称，值为配置对象。
`cache_control`	object

工具配置选项

每个工具（无论是在 default_config 中还是在 configs 中配置）都支持以下字段：

属性	类型	默认值	说明
`enabled`	boolean	`true`	此工具是否启用
`defer_loading`	boolean	`false`	如果为 true，工具描述最初不会发送给模型。与工具搜索工具一起使用。

配置合并

配置值按以下优先级合并（从高到低）：

configs 中的工具特定设置
集合级别的 default_config
系统默认值

示例：

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "defer_loading": true
  },
  "configs": {
    "search_events": {
      "enabled": false
    }
  }
}

结果：

search_events：enabled: false（来自 configs），defer_loading: true（来自 default_config）
所有其他工具：enabled: true（系统默认值），defer_loading: true（来自 default_config）

常见配置模式

使用默认配置启用所有工具

最简单的模式——启用服务器中的所有工具：

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp"
}

允许列表——仅启用特定工具

将 enabled: false 设为默认值，然后显式启用特定工具：

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false
  },
  "configs": {
    "search_events": {
      "enabled": true
    },
    "create_event": {
      "enabled": true
    }
  }
}

拒绝列表——禁用特定工具

默认启用所有工具，然后显式禁用不需要的工具：

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "configs": {
    "delete_all_events": {
      "enabled": false
    },
    "share_calendar_publicly": {
      "enabled": false
    }
  }
}

混合——带按工具配置的允许列表

将允许列表与每个工具的自定义配置结合使用：

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false,
    "defer_loading": true
  },
  "configs": {
    "search_events": {
      "enabled": true,
      "defer_loading": false
    },
    "list_events": {
      "enabled": true
    }
  }
}

在此示例中：

search_events 已启用，defer_loading: false
list_events 已启用，defer_loading: true（从 default_config 继承）
所有其他工具均已禁用

验证规则

API 强制执行以下验证规则：

服务器必须存在：MCPToolset 中的 mcp_server_name 必须与 mcp_servers 数组中定义的服务器匹配
服务器必须被使用：mcp_servers 中定义的每个 MCP 服务器必须被恰好一个 MCPToolset 引用
每个服务器唯一工具集：每个 MCP 服务器只能被一个 MCPToolset 引用
未知工具名称：如果 configs 中的工具名称在 MCP 服务器上不存在，则会记录后端警告但不返回错误（MCP 服务器可能具有动态工具可用性）

响应内容类型

当 Claude 使用 MCP 工具时，响应将包含两种新的内容块类型：

MCP 工具使用块

{
  "type": "mcp_tool_use",
  "id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "name": "echo",
  "server_name": "example-mcp",
  "input": { "param1": "value1", "param2": "value2" }
}

MCP 工具结果块

{
  "type": "mcp_tool_result",
  "tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "is_error": false,
  "content": [
    {
      "type": "text",
      "text": "Hello"
    }
  ]
}

多个 MCP 服务器

您可以通过在 mcp_servers 中包含多个服务器定义，并在 tools 数组中为每个服务器提供相应的 MCPToolset 来连接到多个 MCP 服务器：

{
  "model": "claude-opus-4-6",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "user",
      "content": "Use tools from both mcp-server-1 and mcp-server-2 to complete this task"
    }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example1.com/sse",
      "name": "mcp-server-1",
      "authorization_token": "TOKEN1"
    },
    {
      "type": "url",
      "url": "https://mcp.example2.com/sse",
      "name": "mcp-server-2",
      "authorization_token": "TOKEN2"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-1"
    },
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-2",
      "default_config": {
        "defer_loading": true
      }
    }
  ]
}

身份验证

对于需要 OAuth 身份验证的 MCP 服务器，您需要获取访问令牌。MCP 连接器 beta 支持在 MCP 服务器定义中传递 authorization_token 参数。 API 使用者需要在进行 API 调用之前处理 OAuth 流程并获取访问令牌，并根据需要刷新令牌。

获取用于测试的访问令牌

MCP 检查器可以引导您完成获取用于测试目的的访问令牌的过程。

使用以下命令运行检查器。您需要在机器上安装 Node.js。
```
npx @modelcontextprotocol/inspector
```
在左侧边栏中，对于"传输类型"，选择"SSE"或"Streamable HTTP"。
输入 MCP 服务器的 URL。
在右侧区域，点击"需要配置身份验证？"后面的"打开身份验证设置"按钮。
点击"快速 OAuth 流程"并在 OAuth 屏幕上授权。
按照检查器"OAuth 流程进度"部分中的步骤操作，点击"继续"直到到达"身份验证完成"。
复制 access_token 值。

使用访问令牌

使用上述 OAuth 流程获取访问令牌后，您可以在 MCP 服务器配置中使用它：

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "authenticated-server",
      "authorization_token": "YOUR_ACCESS_TOKEN_HERE"
    }
  ]
}

有关 OAuth 流程的详细说明，请参阅 MCP 规范中的授权部分。

客户端 MCP 辅助函数（TypeScript）

如果您自行管理 MCP 客户端连接（例如，使用本地 stdio 服务器、MCP 提示或 MCP 资源），TypeScript SDK 提供了在 MCP 类型和 Claude API 类型之间转换的辅助函数。这消除了在将 MCP SDK 与 Anthropic SDK 一起使用时的手动转换代码。

这些辅助函数目前仅在 TypeScript SDK 中可用。

当您有可通过 URL 访问的远程服务器且只需要工具支持时，请使用 mcp_servers API 参数。如果您使用的是 Agent SDK，MCP 连接将自动管理。当您需要本地服务器、提示、资源或对基础 SDK 连接有更多控制时，请使用客户端辅助函数。

安装

同时安装 Anthropic SDK 和 MCP SDK：

npm install @anthropic-ai/sdk @modelcontextprotocol/sdk

可用辅助函数

从 beta 命名空间导入辅助函数：

import {
  mcpTools,
  mcpMessages,
  mcpResourceToContent,
  mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";

辅助函数	说明
`mcpTools(tools, mcpClient)`	将 MCP 工具转换为 Claude API 工具，用于 `client.beta.messages.toolRunner()`
`mcpMessages(messages)`	将 MCP 提示消息转换为 Claude API 消息格式
`mcpResourceToContent(resource)`	将 MCP 资源转换为 Claude API 内容块
`mcpResourceToFile(resource)`	将 MCP 资源转换为用于上传的文件对象

使用 MCP 工具

将 MCP 工具转换为与 SDK 的工具运行器一起使用，该运行器自动处理工具执行：

import Anthropic from "@anthropic-ai/sdk";
import { mcpTools } from "@anthropic-ai/sdk/helpers/beta/mcp";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const anthropic = new Anthropic();

// 连接到 MCP 服务器
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);

// 列出工具并将其转换为 Claude API 格式
const { tools } = await mcpClient.listTools();
const runner = await anthropic.beta.messages.toolRunner({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What tools do you have available?" }],
  tools: mcpTools(tools, mcpClient)
});

使用 MCP 提示

将 MCP 提示消息转换为 Claude API 消息格式：

import { mcpMessages } from "@anthropic-ai/sdk/helpers/beta/mcp";

const { messages } = await mcpClient.getPrompt({ name: "my-prompt" });
const response = await anthropic.beta.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});

使用 MCP 资源

将 MCP 资源转换为内容块以包含在消息中，或转换为用于上传的文件对象：

import { mcpResourceToContent, mcpResourceToFile } from "@anthropic-ai/sdk/helpers/beta/mcp";

// 作为消息中的内容块
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        mcpResourceToContent(resource),
        { type: "text", text: "Summarize this document" }
      ]
    }
  ]
});

// 作为文件上传
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
await anthropic.beta.files.upload({ file: mcpResourceToFile(fileResource) });

错误处理

如果 MCP 值不受 Claude API 支持，转换函数将抛出 UnsupportedMCPValueError。这可能发生在不支持的内容类型、MIME 类型或非 HTTP 资源链接的情况下。

数据保留

MCP 连接器不在 ZDR 安排的覆盖范围内。与 MCP 服务器交换的数据，包括工具定义和执行结果，将根据 Anthropic 的标准数据保留政策进行保留。

有关所有功能的 ZDR 资格，请参阅 API 和数据保留。

迁移指南

如果您正在使用已弃用的 mcp-client-2025-04-04 beta 请求头，请按照本指南迁移到新版本。

主要变更

新的 beta 请求头：从 mcp-client-2025-04-04 更改为 mcp-client-2025-11-20
工具配置已移动：工具配置现在作为 MCPToolset 对象位于 tools 数组中，而不是在 MCP 服务器定义中
更灵活的配置：新模式支持允许列表、拒绝列表和按工具配置

迁移步骤

之前（已弃用）：

{
  "model": "claude-opus-4-6",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["tool1", "tool2"]
      }
    }
  ]
}

之后（当前）：

{
  "model": "claude-opus-4-6",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "example-mcp",
      "default_config": {
        "enabled": false
      },
      "configs": {
        "tool1": {
          "enabled": true
        },
        "tool2": {
          "enabled": true
        }
      }
    }
  ]
}

常见迁移模式

旧模式	新模式
无 `tool_configuration`（所有工具已启用）	无 `default_config` 或 `configs` 的 MCPToolset
`tool_configuration.enabled: false`	带 `default_config.enabled: false` 的 MCPToolset
`tool_configuration.allowed_tools: [...]`	带 `default_config.enabled: false` 且在 `configs` 中启用特定工具的 MCPToolset

已弃用版本：mcp-client-2025-04-04

此版本已弃用。请使用上方的迁移指南迁移到 mcp-client-2025-11-20。

之前版本的 MCP 连接器直接在 MCP 服务器定义中包含工具配置：

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["example_tool_1", "example_tool_2"]
      }
    }
  ]
}

已弃用字段说明

属性	类型	说明
`tool_configuration`	object	已弃用：请改用 `tools` 数组中的 MCPToolset
`tool_configuration.enabled`	boolean	已弃用：请改用 MCPToolset 中的 `default_config.enabled`
`tool_configuration.allowed_tools`	array	已弃用：请改用 MCPToolset 中带 `configs` 的允许列表模式

curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1000,
    "messages": [{"role": "user", "content": "What tools do you have available?"}],
    "mcp_servers": [
      {
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse",
        "name": "example-mcp",
        "authorization_token": "YOUR_TOKEN"
      }
    ],
    "tools": [
      {
        "type": "mcp_toolset",
        "mcp_server_name": "example-mcp"
      }
    ]
  }'