MCP

MCP 连接器

使用 Claude 的 Model Context Protocol (MCP) 连接器直接从 Messages API 连接到远程 MCP 服务器

Claude 的 Model Context Protocol (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 服务器中的所有工具：

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",
    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	否	OAuth 授权令牌，如果 MCP 服务器需要。请参阅 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-7",
  "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 值。
将其粘贴到 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 类型之间转换的助手函数。这在与 Anthropic SDK 一起使用 MCP 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();

// 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-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";

// 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-6",
  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 连接器不受 ZDR 安排的覆盖。与 MCP 服务器交换的数据，包括工具定义和执行结果，根据 Anthropic 的标准数据保留政策保留。

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

迁移指南

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

关键变化

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

迁移步骤

之前（已弃用）：

{
  "model": "claude-opus-4-7",
  "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-7",
  "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?

MCP

MCP 连接器

使用 Claude 的 Model Context Protocol (MCP) 连接器直接从 Messages API 连接到远程 MCP 服务器

Claude 的 Model Context Protocol (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 服务器中的所有工具：

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",
    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	否	OAuth 授权令牌，如果 MCP 服务器需要。请参阅 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-7",
  "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 检查器可以指导您完成获取用于测试目的的访问令牌的过程。

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

// 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-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";

// 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-6",
  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 连接器不受 ZDR 安排的覆盖。与 MCP 服务器交换的数据，包括工具定义和执行结果，根据 Anthropic 的标准数据保留政策保留。

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

迁移指南

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

关键变化

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

迁移步骤

之前（已弃用）：

{
  "model": "claude-opus-4-7",
  "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-7",
  "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?