MCP 连接器

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

核心功能

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

限制

• 在 MCP 规范的功能集中，目前仅支持工具调用。
• 服务器必须通过 HTTP 公开暴露（支持 Streamable HTTP 和 SSE 传输）。本地 STDIO 服务器无法直接连接。
• MCP 连接器在 Claude API、Claude Platform on AWS 和 Microsoft Foundry 上可用。目前在 Amazon Bedrock 或 Vertex AI 上不可用。

在 Messages API 中使用 MCP 连接器

MCP 连接器使用两个组件：

1. MCP 服务器定义（mcp_servers 数组）：定义服务器连接详情（URL、认证）
2. MCP 工具集（tools 数组）：配置启用哪些工具以及如何配置

基本示例

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

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

ant beta:messages create --beta mcp-client-2025-11-20 <<'YAML'
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
YAML

import anthropic

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)

import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic();

const response = await anthropic.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"]
});

console.log(response);

using Anthropic;
using Anthropic.Models.Beta.Messages;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

AnthropicClient client = new();

var parameters = new MessageCreateParams
{
    Model = Model.ClaudeOpus4_7,
    MaxTokens = 1000,
    Messages = new List<BetaMessageParam>
    {
        new() { Role = Role.User, Content = "What tools do you have available?" }
    },
    McpServers = new List<BetaRequestMcpServerUrlDefinition>
    {
        new()
        {
            Url = "https://example-server.modelcontextprotocol.io/sse",
            Name = "example-mcp",
            AuthorizationToken = "YOUR_TOKEN"
        }
    },
    Tools = new List<BetaToolUnion>
    {
        new BetaMcpToolset("example-mcp")
    },
    Betas = new List<string> { "mcp-client-2025-11-20" }
};

var message = await client.Beta.Messages.Create(parameters);
Console.WriteLine(message);

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/anthropics/anthropic-sdk-go"
)

func main() {
	client := anthropic.NewClient()

	response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
		Model:     anthropic.ModelClaudeOpus4_7,
		MaxTokens: 1000,
		Messages: []anthropic.BetaMessageParam{
			anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What tools do you have available?")),
		},
		MCPServers: []anthropic.BetaRequestMCPServerURLDefinitionParam{
			{
				URL:                "https://example-server.modelcontextprotocol.io/sse",
				Name:               "example-mcp",
				AuthorizationToken: anthropic.String("YOUR_TOKEN"),
			},
		},
		Tools: []anthropic.BetaToolUnionParam{
			{OfMCPToolset: &anthropic.BetaMCPToolsetParam{
				MCPServerName: "example-mcp",
			}},
		},
		Betas: []anthropic.AnthropicBeta{
			anthropic.AnthropicBetaMCPClient2025_11_20,
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.messages.BetaMcpToolset;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

void main() {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();

    MessageCreateParams params = MessageCreateParams.builder()
        .model(Model.CLAUDE_OPUS_4_7)
        .maxTokens(1000L)
        .addUserMessage("What tools do you have available?")
        .addMcpServer(BetaRequestMcpServerUrlDefinition.builder()
            .url("https://example-server.modelcontextprotocol.io/sse")
            .name("example-mcp")
            .authorizationToken("YOUR_TOKEN")
            .build())
        .addTool(BetaMcpToolset.builder()
            .mcpServerName("example-mcp")
            .build())
        .addBeta("mcp-client-2025-11-20")
        .build();

    BetaMessage response = client.beta().messages().create(params);
    IO.println(response);
}

<?php

use Anthropic\Client;

$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));

$message = $client->beta->messages->create(
    maxTokens: 1000,
    messages: [
        ['role' => 'user', 'content' => 'What tools do you have available?']
    ],
    model: 'claude-opus-4-7',
    mcpServers: [
        [
            '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'],
);

echo $message;

require "anthropic"

client = Anthropic::Client.new

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"]
)

puts 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-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 检查器可以指导您完成获取测试用访问令牌的过程。

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

   npx @modelcontextprotocol/inspector
   

2. 在左侧边栏中，对于"传输类型"，选择"SSE"或"Streamable HTTP"。

3. 输入 MCP 服务器的 URL。

4. 在右侧区域，点击"需要配置认证？"后的"打开认证设置"按钮。

5. 点击"快速 OAuth 流程"并在 OAuth 屏幕上授权。

6. 按照检查器的"OAuth 流程进度"部分中的步骤操作，点击"继续"直到到达"认证完成"。

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 辅助工具（TypeScript）

如果您管理自己的 MCP 客户端连接（例如使用本地 stdio 服务器、MCP 提示或 MCP 资源），TypeScript SDK 提供辅助函数，可在 MCP 类型和 Claude API 类型之间进行转换。这消除了在使用 MCP SDK 和 Anthropic 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";

使用 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();

// 连接到 MCP 服务器
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);

// 列出工具并为 Claude API 转换
const { tools } = await mcpClient.listTools();
const finalMessage = 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)
});

console.log(finalMessage);

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

console.log(response);

使用 MCP 资源

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

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

// 作为消息中的内容块
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" }
      ]
    }
  ]
});

// 作为文件上传
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 头，请按照本指南迁移到新版本。

主要变更

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

迁移步骤

之前（已弃用）：

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

常见迁移模式

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

弃用字段说明