MessagesMCP

MCP 连接器

无需 MCP 客户端，直接从 Messages API 连接到远程 MCP 服务器，并对单个工具进行允许列表、拒绝列表或配置。

Claude 的 "Model Context Protocol"，即 MCP 连接器功能使您能够直接从 Messages API 连接到远程 MCP 服务器，而无需单独的 MCP 客户端。

主要功能

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

Claude 何时使用 MCP 工具

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

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

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

限制

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

在 Messages API 中使用 MCP 连接器

MCP 连接器使用两个组件：

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

基本示例

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    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	否	此工具集的 prompt caching（提示缓存）缓存断点配置。

工具配置选项

每个工具（无论是在 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-5",
  "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 连接器测试版支持在 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 辅助函数

如果您自行管理 MCP 客户端连接（例如，使用本地 stdio 服务器、MCP 提示或 MCP 资源），SDK 提供了在 MCP 类型与 Claude API 类型之间进行转换的辅助函数。当您将适用于您所用语言的 MCP SDK（例如 TypeScript MCP SDK）与 Anthropic SDK 一起使用时，这可以省去手动编写转换代码。

安装

同时安装 Anthropic SDK 和 MCP SDK：

MCP 辅助函数包含在 mcp extra 中，需要 Python 3.10 或更高版本：

pip install "anthropic[mcp]"

可用的辅助函数

导入适用于您所用语言的辅助函数：

from anthropic.lib.tools.mcp import (
    async_mcp_tool,
    mcp_message,
    mcp_resource_to_content,
    mcp_resource_to_file,
)

辅助函数的名称和确切签名遵循各语言的惯例；下表显示的是 TypeScript 形式：

辅助函数	说明
`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 的工具运行器一起使用，该运行器会自动处理工具执行：

from anthropic.lib.tools.mcp import async_mcp_tool
from mcp import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

client = AsyncAnthropic()


async def main() -> None:
    # 连接到 MCP 服务器
    server_params = StdioServerParameters(command="mcp-server")
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as mcp_client:
            await mcp_client.initialize()

            # 列出工具并将其转换为 Claude API 格式
            tools_result = await mcp_client.list_tools()
            runner = client.beta.messages.tool_runner(
                model="claude-opus-5",
                max_tokens=1024,
                messages=[
                    {"role": "user", "content": "What tools do you have available?"},
                ],
                tools=[async_mcp_tool(tool, mcp_client) for tool in tools_result.tools],
            )

            final_message = await runner.until_done()
            print(final_message)


asyncio.run(main())

使用 MCP 提示

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

from anthropic.lib.tools.mcp import mcp_message

prompt = await mcp_client.get_prompt(name="my-prompt")
response = await client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[mcp_message(message) for message in prompt.messages],
)

print(response)

使用 MCP 资源

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

from anthropic.lib.tools.mcp import (
    mcp_resource_to_content,
    mcp_resource_to_file,
)

# 作为消息中的内容块
resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
response = await client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                mcp_resource_to_content(resource),
                {"type": "text", "text": "Summarize this document"},
            ],
        }
    ],
)
print(response)

# 作为文件上传
file_resource = await mcp_client.read_resource(
    uri="file:///path/to/data.json",
)
uploaded = await client.files.upload(
    file=mcp_resource_to_file(file_resource),
)
print(uploaded.id)

错误处理

如果某个 MCP 值不受 Claude API 支持，转换函数会抛出 UnsupportedMCPValueError（在 Go 中，辅助函数返回 UnsupportedValueError；在 Java 和 C# 中，它们抛出 AnthropicInvalidDataException）。这可能发生在不受支持的内容类型、MIME 类型或资源链接上（请在转换之前使用您的 MCP 客户端解析资源链接）。

批量请求

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

数据保留

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

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

迁移指南

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

主要变更

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

迁移步骤

之前（已弃用）：

{
  "model": "claude-opus-5",
  "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-5",
  "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 连接器的先前版本将工具配置直接包含在 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` 的允许列表模式

Compatibility

Supported platforms	Claude APIBeta Claude Platform on AWSBeta Microsoft FoundryBeta

主要功能

Claude 何时使用 MCP 工具

限制

在 Messages API 中使用 MCP 连接器

基本示例

MCP 服务器配置

字段说明

MCP 工具集配置

基本结构

字段说明

工具配置选项

配置合并

常见配置模式

以默认配置启用所有工具

允许列表：仅启用特定工具

拒绝列表：禁用特定工具

混合：带有按工具配置的允许列表

验证规则

响应内容类型

MCP 工具使用块

MCP 工具结果块

多个 MCP 服务器

身份验证

获取用于测试的访问令牌

使用访问令牌

客户端 MCP 辅助函数

安装

可用的辅助函数

使用 MCP 工具

使用 MCP 提示

使用 MCP 资源

错误处理

批量请求

数据保留

迁移指南

主要变更

迁移步骤

常见迁移模式

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

已弃用字段说明

Compatibility

主要功能

Claude 何时使用 MCP 工具

限制

在 Messages API 中使用 MCP 连接器

基本示例

MCP 服务器配置

字段说明

MCP 工具集配置

基本结构

字段说明

工具配置选项

配置合并

常见配置模式

以默认配置启用所有工具

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

拒绝列表：禁用特定工具

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

验证规则

响应内容类型

MCP 工具使用块

MCP 工具结果块

多个 MCP 服务器

身份验证

获取用于测试的访问令牌

使用访问令牌

客户端 MCP 辅助函数

安装

可用的辅助函数

使用 MCP 工具

使用 MCP 提示

使用 MCP 资源

错误处理

批量请求

数据保留

迁移指南

主要变更

迁移步骤

常见迁移模式

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

已弃用字段说明