MCP连接器 MCP connector —— Anthropic

MCP connector

MCP连接器

https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#use-mcp-tools

Claude's Model Context Protocol (MCP) connector feature enables you to connect to remote MCP servers directly from the Messages API without a separate MCP client.

Current version: This feature requires the beta header:"anthropic-beta": "mcp-client-2025-11-20"

The previous version (mcp-client-2025-04-04) is deprecated. See the deprecated version documentation below.

This feature isnoteligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

Key features

• Direct API integration: Connect to MCP servers without implementing an MCP client
• Tool calling support: Access MCP tools through the Messages API
• Flexible tool configuration: Enable all tools, allowlist specific tools, or denylist unwanted tools
• Per-tool configuration: Configure individual tools with custom settings
• OAuth authentication: Support for OAuth Bearer tokens for authenticated servers
• Multiple servers: Connect to multiple MCP servers in a single request

主要特点

直接API集成：无需实现MCP客户端即可连接MCP服务器
工具调用支持：通过消息API访问MCP工具
灵活的工具配置：启用所有工具、允许特定工具或禁止不需要的工具
单工具配置：使用自定义设置单独配置每个工具
OAuth认证：支持通过OAuth Bearer令牌连接认证服务器
多服务器支持：在单个请求中连接多个MCP服务器

Limitations

• Of the feature set of the MCP specification, only tool calls are currently supported.
• The server must be publicly exposed through HTTP (supports both Streamable HTTP and SSE transports). Local STDIO servers cannot be connected directly.
• The MCP connector is currently not supported on Amazon Bedrock and Google Vertex.

限制

在MCP规范的功能集中，目前仅支持工具调用功能。 服务器必须通过HTTP公开暴露（同时支持可流式HTTP和SSE传输协议）。无法直接连接本地STDIO服务器。 目前亚马逊Bedrock和谷歌Vertex平台不支持MCP连接器。

Using the MCP connector in the Messages API

The MCP connector uses two components:

1. MCP Server Definition(mcp_serversarray): Defines server connection details (URL, authentication)
2. MCP Toolset(toolsarray): Configures which tools to enable and how to configure them

在消息API中使用MCP连接器

MCP连接器使用两个组件：

MCP服务器定义（mcp_servers数组）：定义服务器连接详情（URL、认证信息） MCP工具集（tools数组）：配置要启用的工具及其设置方式

Basic example

This example enables all tools from an MCP server with default configuration:

cURLCLIPythonTypeScriptC#GoJavaPHPRuby

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 server configuration

Each MCP server in themcp_serversarray defines the connection details:

{ "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse", "name": "example-mcp", "authorization_token": "YOUR_TOKEN" }

Field descriptions

MCP toolset configuration

The MCPToolset lives in thetoolsarray and configures which tools from the MCP server are enabled and how they should be configured.

Basic structure

{ "type": "mcp_toolset", "mcp_server_name": "example-mcp", "default_config": { "enabled": true, "defer_loading": false }, "configs": { "specific_tool_name": { "enabled": true, "defer_loading": true } } }

Field descriptions

Tool configuration options

Each tool (whether configured indefault_configor inconfigs) supports the following fields:

For the full directory of Anthropic-provided tools and optional properties likedefer_loading, see the Tool reference. For searching across large tool sets, see Tool search tool.

Configuration merging

Configuration values merge with this precedence (highest to lowest):

1. Tool-specific settings inconfigs
2. Set-leveldefault_config
3. System defaults

Example:

{ "type": "mcp_toolset", "mcp_server_name": "google-calendar-mcp", "default_config": { "defer_loading": true }, "configs": { "search_events": { "enabled": false } } }

Results in:

• search_events:enabled: false(from configs),defer_loading: true(from default_config)
• All other tools:enabled: true(system default),defer_loading: true(from default_config)

Common configuration patterns

Enable all tools with default configuration

The simplest pattern - enable all tools from a server:

{ "type": "mcp_toolset", "mcp_server_name": "google-calendar-mcp" }

Allowlist - Enable only specific tools

Setenabled: falseas the default, then explicitly enable specific tools:

{ "type": "mcp_toolset", "mcp_server_name": "google-calendar-mcp", "default_config": { "enabled": false }, "configs": { "search_events": { "enabled": true }, "create_event": { "enabled": true } } }

Denylist - Disable specific tools

Enable all tools by default, then explicitly disable unwanted tools:

{ "type": "mcp_toolset", "mcp_server_name": "google-calendar-mcp", "configs": { "delete_all_events": { "enabled": false }, "share_calendar_publicly": { "enabled": false } } }

Mixed - Allowlist with per-tool configuration

Combine allowlisting with custom configuration for each tool:

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

In this example:

• search_eventsis enabled withdefer_loading: false
• list_eventsis enabled withdefer_loading: true(inherited from default_config)
• All other tools are disabled

Validation rules

The API enforces these validation rules:

• Server must exist: Themcp_server_namein an MCPToolset must match a server defined in themcp_serversarray
• Server must be used: Every MCP server defined inmcp_serversmust be referenced by exactly one MCPToolset
• Unique toolset per server: Each MCP server can only be referenced by one MCPToolset
• Unknown tool names: If a tool name inconfigsdoesn't exist on the MCP server, a backend warning is logged but no error is returned (MCP servers may have dynamic tool availability)

Response content types

When Claude uses MCP tools, the response will include two new content block types:

MCP Tool Use Block

{ "type": "mcp_tool_use", "id": "mcptoolu_014Q35RayjACSWkSj4X2yov1", "name": "echo", "server_name": "example-mcp", "input": { "param1": "value1", "param2": "value2" } }

MCP Tool Result Block

{ "type": "mcp_tool_result", "tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1", "is_error": false, "content": [ { "type": "text", "text": "Hello" } ] }

Multiple MCP servers

You can connect to multiple MCP servers by including multiple server definitions inmcp_serversand a corresponding MCPToolset for each in thetoolsarray:

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

Authentication

For MCP servers that require OAuth authentication, you'll need to obtain an access token. The MCP connector beta supports passing anauthorization_tokenparameter in the MCP server definition. API consumers are expected to handle the OAuth flow and obtain the access token prior to making the API call, as well as refreshing the token as needed.

Obtaining an access token for testing

The MCP inspector can guide you through the process of obtaining an access token for testing purposes.

1. Run the inspector with the following command. You need Node.js installed on your machine.

   npx @modelcontextprotocol/inspector

2. In the sidebar on the left, for "Transport type", select either "SSE" or "Streamable HTTP".

3. Enter the URL of the MCP server.

4. In the right area, click on the "Open Auth Settings" button after "Need to configure authentication?".

5. Click "Quick OAuth Flow" and authorize on the OAuth screen.

6. Follow the steps in the "OAuth Flow Progress" section of the inspector and click "Continue" until you reach "Authentication complete".

7. Copy theaccess_tokenvalue.

8. Paste it into theauthorization_tokenfield in your MCP server configuration.

Using the access token

Once you've obtained an access token using either OAuth flow above, you can use it in your MCP server configuration:

{ "mcp_servers": [ { "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse", "name": "authenticated-server", "authorization_token": "YOUR_ACCESS_TOKEN_HERE" } ] }

For detailed explanations of the OAuth flow, refer to the Authorization section in the MCP specification.

Client-side MCP helpers (TypeScript)

If you manage your own MCP client connection (for example, with local stdio servers, MCP prompts, or MCP resources), the TypeScript SDK provides helper functions that convert between MCP types and Claude API types. This eliminates manual conversion code when using the MCP SDK alongside the Anthropic SDK.

These helpers are currently available in the TypeScript SDK only.

Use the mcp_servers API parameter when you have remote servers accessible via URL and only need tool support. Use the client-side helpers when you need local servers, prompts, resources, or more control over the connection with the base SDK.

Installation

Install both the Anthropic SDK and the MCP SDK:

npm install @anthropic-ai/sdk @modelcontextprotocol/sdk

Available helpers

Import the helpers from the beta namespace:

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

Use MCP tools

Convert MCP tools for use with the SDK's tool runner, which handles tool execution automatically:

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-opus-4-7", max_tokens: 1024, messages: [{ role: "user", content: "What tools do you have available?" }], tools: mcpTools(tools, mcpClient) });

Use MCP prompts

Convert MCP prompt messages into Claude API message format:

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-7", max_tokens: 1024, messages: mcpMessages(messages) });

Use MCP resources

Convert MCP resources into content blocks to include in messages, or into file objects for upload:

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

Error handling

The conversion functions throwUnsupportedMCPValueErrorif an MCP value isn't supported by the Claude API. This can happen with unsupported content types, MIME types, or non-HTTP resource links.

Data retention

The MCP Connector is not covered by ZDR arrangements. Data exchanged with MCP servers, including tool definitions and execution results, is retained according to Anthropic's standard data retention policy.

For ZDR eligibility across all features, see API and data retention.

Migration guide

If you're using the deprecatedmcp-client-2025-04-04beta header, follow this guide to migrate to the new version.

Key changes

1. New beta header: Change frommcp-client-2025-04-04tomcp-client-2025-11-20
2. Tool configuration moved: Tool configuration now lives in thetoolsarray as MCPToolset objects, not in the MCP server definition
3. More flexible configuration: New pattern supports allowlisting, denylisting, and per-tool configuration

Migration steps

Before (deprecated):

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

After (current):

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

Common migration patterns

Deprecated version: mcp-client-2025-04-04

This version is deprecated. Migrate tomcp-client-2025-11-20using the migration guide above.

The previous version of the MCP connector included tool configuration directly in the MCP server definition:

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

Deprecated field descriptions