MCP 连接器

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



主要功能

• 直接 API 集成：无需实现 MCP 客户端即可连接到 MCP 服务器
• 工具调用支持：通过 Messages API 访问 MCP 工具
• 灵活的工具配置：启用所有工具、允许列表（allowlist）特定工具或拒绝列表（denylist）不需要的工具
• 按工具配置：使用自定义设置配置单个工具
• 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、Claude Platform on AWS 和 Microsoft Foundry 上使用。在 Microsoft Foundry 上，MCP 连接器需要 Hosted on Anthropic 部署。目前在 Amazon Bedrock 或 Google Cloud 上不可用。



在 Messages API 中使用 MCP 连接器

MCP 连接器使用两个组件：

1. MCP 服务器定义（mcp_servers 数组）：定义服务器连接详细信息（URL、身份验证）
2. 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"
}



字段说明



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
    }
  }
}



字段说明



工具配置选项

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

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



配置合并

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

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

示例：

{
  "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 连接器 beta 支持在 MCP 服务器定义中传递 authorization_token 参数。 API 使用者需要在进行 API 调用之前处理 OAuth 流程并获取访问令牌，并根据需要刷新令牌。



获取用于测试的访问令牌

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

1. 使用以下命令运行 inspector。您的机器上需要安装 Node.js。

   npx @modelcontextprotocol/inspector

   

2. 在左侧边栏中，对于 "Transport type"，选择 "SSE" 或 "Streamable HTTP"。

3. 输入 MCP 服务器的 URL。

4. 在右侧区域，点击 "Need to configure authentication?" 后面的 "Open Auth Settings" 按钮。

5. 点击 "Quick OAuth Flow" 并在 OAuth 屏幕上进行授权。

6. 按照 inspector 中 "OAuth Flow Progress" 部分的步骤操作，并点击 "Continue" 直到到达 "Authentication complete"。

7. 复制 access_token 的值。

8. 将其粘贴到 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 类型之间进行转换的辅助函数。当您在 Anthropic SDK 之外同时使用适用于您的语言的 MCP SDK（例如 TypeScript MCP SDK）时，这可以消除手动转换代码。



安装

同时安装 Anthropic SDK 和 MCP SDK：

pip install "anthropic[mcp]"



可用的辅助函数

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

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

辅助函数的名称和确切签名遵循每种语言的约定；下表显示的是 TypeScript 形式：



使用 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.beta.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 beta 标头，请按照本指南迁移到新版本。



主要变更

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



迁移步骤

之前（已弃用）：

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



常见迁移模式



已弃用版本：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"]
      }
    }
  ]
}



已弃用字段说明