消息MCP

MCP 连接器

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

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

之前的版本（mcp-client-2025-04-04）已弃用。请参阅已弃用版本：mcp-client-2025-04-04。

此功能不符合零数据保留（ZDR）的条件。数据将根据该功能的标准保留策略进行保留。

主要功能

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

Claude 何时使用 MCP 工具

连接 MCP 服务器后，当用户的请求与某个工具所描述的功能相匹配时，Claude 就会调用该工具——无论是显式匹配（例如"在 Jira 中搜索未解决的 bug"）还是隐式匹配（例如在已连接 Jira 服务器的情况下询问"是什么阻碍了发布？"）。

对于有关已连接服务的常识性问题，Claude 不会调用 MCP 工具。在已连接 Notion 服务器的情况下询问"Notion 数据库是如何工作的？"会直接得到回答；而询问"我的 Projects 数据库里有什么？"则会触发工具调用。

您可以通过系统提示来引导 Claude 调用 MCP 工具的积极程度。有关通用指导和示例措辞，请参阅 Claude 何时使用工具。

限制

在 MCP 规范的功能集中，目前仅支持工具调用。
服务器必须通过 HTTP 公开暴露（支持 Streamable HTTP 和 SSE 两种传输方式）。无法直接连接本地 STDIO 服务器。
MCP 连接器可在 Claude API、AWS 上的 Claude Platform 和 Microsoft Foundry 上使用。目前在 Amazon Bedrock 或 Vertex AI 上不可用。

在 Messages API 中使用 MCP 连接器

MCP 连接器使用两个组件：

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

基本示例

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
    betas=["mcp-client-2025-11-20"],
)

print(response)

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，则初始时不会将工具描述发送给模型。与工具搜索工具配合使用。

有关 Anthropic 提供的工具的完整目录以及 defer_loading 等可选属性，请参阅工具参考。有关在大型工具集中进行搜索的信息，请参阅工具搜索工具。

配置合并

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

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-8",
  "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
      }
    }
  ]
}

当有许多工具可用时，Claude 会根据工具名称和描述进行选择。清晰、具体的工具描述可以提高选择的准确性。对于大型工具集（跨多个服务器的数十个工具），建议结合工具搜索工具启用 defer_loading，以便每次查询只呈现相关的工具。

身份验证

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

获取用于测试的访问令牌

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

使用以下命令运行 inspector。您的机器上需要安装 Node.js。
```
npx @modelcontextprotocol/inspector
```
在左侧边栏中，对于 "Transport type"，选择 "SSE" 或 "Streamable HTTP"。
输入 MCP 服务器的 URL。
在右侧区域中，点击 "Need to configure authentication?" 后面的 "Open Auth Settings" 按钮。
点击 "Quick OAuth Flow" 并在 OAuth 界面上进行授权。
按照 inspector 中 "OAuth Flow Progress" 部分的步骤操作，点击 "Continue" 直到到达 "Authentication complete"。
复制 access_token 的值。
将其粘贴到您的 MCP 服务器配置中的 authorization_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 参数。当您需要本地服务器、提示、资源，或需要通过基础 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 { 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 finalMessage = await anthropic.beta.messages.toolRunner({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What tools do you have available?" }],
  tools: mcpTools(tools, mcpClient)
});

console.log(finalMessage);

使用 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-opus-4-8",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});

console.log(response);

使用 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-opus-4-8",
  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) });

错误处理

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

批量请求

您可以在消息批处理 API 请求中包含 mcp_servers。通过批处理 API 进行的 MCP 工具调用的定价与常规 Messages API 请求中的定价相同。

数据保留

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-8",
  "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-8",
  "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` 的允许列表模式

Was this page helpful?

消息MCP

MCP 连接器

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

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

之前的版本（mcp-client-2025-04-04）已弃用。请参阅已弃用版本：mcp-client-2025-04-04。

此功能不符合零数据保留（ZDR）的条件。数据将根据该功能的标准保留策略进行保留。

主要功能

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

Claude 何时使用 MCP 工具

您可以通过系统提示来引导 Claude 调用 MCP 工具的积极程度。有关通用指导和示例措辞，请参阅 Claude 何时使用工具。

限制

在 MCP 规范的功能集中，目前仅支持工具调用。
服务器必须通过 HTTP 公开暴露（支持 Streamable HTTP 和 SSE 两种传输方式）。无法直接连接本地 STDIO 服务器。
MCP 连接器可在 Claude API、AWS 上的 Claude Platform 和 Microsoft Foundry 上使用。目前在 Amazon Bedrock 或 Vertex AI 上不可用。

在 Messages API 中使用 MCP 连接器

MCP 连接器使用两个组件：

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

基本示例

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
    betas=["mcp-client-2025-11-20"],
)

print(response)

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，则初始时不会将工具描述发送给模型。与工具搜索工具配合使用。

有关 Anthropic 提供的工具的完整目录以及 defer_loading 等可选属性，请参阅工具参考。有关在大型工具集中进行搜索的信息，请参阅工具搜索工具。

配置合并

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

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-8",
  "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
      }
    }
  ]
}

身份验证

获取用于测试的访问令牌

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

使用以下命令运行 inspector。您的机器上需要安装 Node.js。
```
npx @modelcontextprotocol/inspector
```
在左侧边栏中，对于 "Transport type"，选择 "SSE" 或 "Streamable HTTP"。
输入 MCP 服务器的 URL。
在右侧区域中，点击 "Need to configure authentication?" 后面的 "Open Auth Settings" 按钮。
点击 "Quick OAuth Flow" 并在 OAuth 界面上进行授权。
按照 inspector 中 "OAuth Flow Progress" 部分的步骤操作，点击 "Continue" 直到到达 "Authentication complete"。
复制 access_token 的值。
将其粘贴到您的 MCP 服务器配置中的 authorization_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）

这些辅助函数目前仅在 TypeScript 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 { 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 finalMessage = await anthropic.beta.messages.toolRunner({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What tools do you have available?" }],
  tools: mcpTools(tools, mcpClient)
});

console.log(finalMessage);

使用 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-opus-4-8",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});

console.log(response);

使用 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-opus-4-8",
  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) });

错误处理

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

批量请求

您可以在消息批处理 API 请求中包含 mcp_servers。通过批处理 API 进行的 MCP 工具调用的定价与常规 Messages API 请求中的定价相同。

数据保留

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-8",
  "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-8",
  "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` 的允许列表模式

Was this page helpful?