API 中的 MCP

MCP 连接器

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

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

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

主要特性

直接 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 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 值。

使用访问令牌

使用上述任一 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();

// Connect to an MCP server
const transport = new StdioClientTransport({ command: 'mcp-server', args: [] });
const mcpClient = new Client({ name: 'my-client', version: '1.0.0' });
await mcpClient.connect(transport);

// List tools and convert them for the Claude API
const { tools } = await mcpClient.listTools();
const runner = await anthropic.beta.messages.toolRunner({
  model: 'claude-sonnet-4-5',
  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-5',
  max_tokens: 1024,
  messages: mcpMessages(messages),
});

使用 MCP 资源

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

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

// As a content block in a message
const resource = await mcpClient.readResource({ uri: 'file:///path/to/doc.txt' });
await anthropic.beta.messages.create({
  model: 'claude-sonnet-4-5',
  max_tokens: 1024,
  messages: [
    {
      role: 'user',
      content: [
        mcpResourceToContent(resource),
        { type: 'text', text: 'Summarize this document' },
      ],
    },
  ],
});

// As a file upload
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-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`（所有工具已启用）	MCPToolset 不带 `default_config` 或 `configs`
`tool_configuration.enabled: false`	MCPToolset 带 `default_config.enabled: false`
`tool_configuration.allowed_tools: [...]`	MCPToolset 带 `default_config.enabled: false` 并在 `configs` 中启用特定工具

弃用版本：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?

API 中的 MCP

MCP 连接器

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

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

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

主要特性

直接 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
      }
    }
  ]
}

认证

获取用于测试的访问令牌

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 值。

使用访问令牌

使用上述任一 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 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();

// Connect to an MCP server
const transport = new StdioClientTransport({ command: 'mcp-server', args: [] });
const mcpClient = new Client({ name: 'my-client', version: '1.0.0' });
await mcpClient.connect(transport);

// List tools and convert them for the Claude API
const { tools } = await mcpClient.listTools();
const runner = await anthropic.beta.messages.toolRunner({
  model: 'claude-sonnet-4-5',
  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-5',
  max_tokens: 1024,
  messages: mcpMessages(messages),
});

使用 MCP 资源

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

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

// As a content block in a message
const resource = await mcpClient.readResource({ uri: 'file:///path/to/doc.txt' });
await anthropic.beta.messages.create({
  model: 'claude-sonnet-4-5',
  max_tokens: 1024,
  messages: [
    {
      role: 'user',
      content: [
        mcpResourceToContent(resource),
        { type: 'text', text: 'Summarize this document' },
      ],
    },
  ],
});

// As a file upload
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-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`（所有工具已启用）	MCPToolset 不带 `default_config` 或 `configs`
`tool_configuration.enabled: false`	MCPToolset 带 `default_config.enabled: false`
`tool_configuration.allowed_tools: [...]`	MCPToolset 带 `default_config.enabled: false` 并在 `configs` 中启用特定工具

弃用版本：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?

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"
      }
    ]
  }'