MCP Connector — Kết Nối Claude API Với Công Cụ Bên Ngoài Qua MCP

MCP (Model Context Protocol) Connector cho phép bạn kết nối trực tiếp tới các MCP server từ Messages API mà không cần triển khai MCP client riêng. Đây là tính năng mạnh mẽ giúp Claude truy cập tool từ bên ngoài một cách liền mạch — rất hữu ích khi xây dựng AI agent cho doanh nghiệp.

⚠️ Lưu ý: Tính năng này yêu cầu beta header: "anthropic-beta": "mcp-client-2025-11-20"

Tính Năng Chính

• Tích hợp API trực tiếp: Kết nối tới MCP server mà không cần implement MCP client
• Hỗ trợ tool calling: Truy cập MCP tool qua Messages API
• Cấu hình tool linh hoạt: Bật tất cả tool, allowlist tool cụ thể, hoặc denylist tool không muốn
• Cấu hình từng tool: Tùy chỉnh riêng cho mỗi tool
• Xác thực OAuth: Hỗ trợ OAuth Bearer token cho server cần xác thực
• Nhiều server: Kết nối nhiều MCP server trong cùng một request

Giới hạn

• Chỉ hỗ trợ tool call trong MCP specification — chưa hỗ trợ resource hay prompt
• Server phải expose công khai qua HTTP (hỗ trợ Streamable HTTP và SSE transport). Server STDIO local không kết nối trực tiếp được
• Chưa hỗ trợ trên Amazon Bedrock và Google Vertex

Sử Dụng MCP Connector Trong Messages API

MCP Connector sử dụng 2 thành phần:

1. MCP Server Definition (mảng mcp_servers): Định nghĩa chi tiết kết nối server (URL, xác thực)
2. MCP Toolset (mảng tools): Cấu hình tool nào được bật và cách cấu hình

Ví dụ cơ bản

Ví dụ đơn giản nhất — bật tất cả tool từ một MCP server:

Shell (cURL):

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

Python:

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-6",
    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)

TypeScript:

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

const anthropic = new Anthropic();

const response = await anthropic.beta.messages.create({
  model: "claude-opus-4-6",
  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);

Cấu Hình MCP Server

Mỗi MCP server trong mảng mcp_servers định nghĩa chi tiết kết nối:

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

Thuộc tính	Kiểu	Bắt buộc	Mô tả
type	string	Có	Hiện chỉ hỗ trợ "url"
url	string	Có	URL của MCP server. Phải bắt đầu bằng https://
name	string	Có	Định danh duy nhất cho server này
authorization_token	string	Không	OAuth authorization token nếu server yêu cầu

Cấu Hình MCP Toolset

MCPToolset nằm trong mảng tools và cấu hình tool nào được bật cùng cách cấu hình:

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

Thứ tự ưu tiên cấu hình (từ cao đến thấp)

1. Cấu hình riêng từng tool trong configs
2. default_config cấp toolset
3. Giá trị mặc định hệ thống

Các Pattern Cấu Hình Phổ Biến

Pattern 1: Bật tất cả tool (đơn giản nhất)

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

Pattern 2: Allowlist — Chỉ bật tool cụ thể

Đặt enabled: false mặc định, sau đó bật riêng từng tool cần thiết:

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

Pattern 3: Denylist — Tắt tool cụ thể

Bật tất cả mặc định, tắt riêng tool không muốn:

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

Pattern 4: Kết hợp — Allowlist với cấu hình riêng

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

Trong ví dụ trên: search_events được bật với defer_loading: false; list_events được bật kế thừa defer_loading: true từ default_config; tất cả tool còn lại bị tắt.

Kiểu Response Mới

Khi Claude sử dụng MCP tool, response sẽ có 2 content block type mới:

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

Kết Nối Nhiều MCP Server

Bạn có thể kết nối đồng thời nhiều MCP server bằng cách thêm nhiều server definition trong mcp_servers và tương ứng MCPToolset cho mỗi server trong mảng tools:

{
  "model": "claude-opus-4-6",
  "max_tokens": 1000,
  "messages": [
    { "role": "user", "content": "Use tools from both servers 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 }
    }
  ]
}

Xác Thực OAuth

Đối với MCP server yêu cầu xác thực OAuth, bạn cần lấy access token trước khi gọi API. Claude API hỗ trợ truyền authorization_token trong MCP server definition.

Cách lấy access token để test

Sử dụng MCP Inspector:

1. Chạy inspector: npx @modelcontextprotocol/inspector
2. Chọn "SSE" hoặc "Streamable HTTP" trong Transport type
3. Nhập URL của MCP server
4. Click "Open Auth Settings" → "Quick OAuth Flow"
5. Hoàn tất xác thực và copy access_token
6. Paste vào trường authorization_token trong cấu hình MCP server

Client-side MCP Helper (TypeScript)

Nếu bạn quản lý kết nối MCP client riêng (ví dụ với server STDIO local, MCP prompt, hoặc MCP resource), TypeScript SDK cung cấp các helper function chuyển đổi giữa kiểu MCP và kiểu Claude API.

Cài đặt

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

Các helper có sẵn

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

Helper	Mô tả
mcpTools(tools, mcpClient)	Chuyển đổi MCP tool sang Claude API tool để dùng với toolRunner()
mcpMessages(messages)	Chuyển đổi MCP prompt message sang format Claude API message
mcpResourceToContent(resource)	Chuyển MCP resource sang Claude API content block
mcpResourceToFile(resource)	Chuyển MCP resource sang file object để upload

Ví dụ: Sử dụng MCP tool với tool runner

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

// Kết nối tới 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);

// Liệt kê tool và chuyển đổi cho 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)
});

Ví dụ: Sử dụng MCP prompt

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

Xử lý lỗi

Các function chuyển đổi sẽ throw UnsupportedMCPValueError nếu giá trị MCP không được Claude API hỗ trợ — có thể xảy ra với content type, MIME type không hỗ trợ, hoặc resource link không phải HTTP.

Hướng Dẫn Migration Từ Phiên Bản Cũ

Nếu bạn đang dùng beta header cũ mcp-client-2025-04-04, hãy chuyển sang mcp-client-2025-11-20.

Thay đổi chính

1. Beta header mới: Đổi từ mcp-client-2025-04-04 sang mcp-client-2025-11-20
2. Tool configuration đã di chuyển: Cấu hình tool giờ nằm trong mảng tools dạng MCPToolset, không còn trong MCP server definition
3. Linh hoạt hơn: Pattern mới hỗ trợ allowlist, denylist và cấu hình từng tool

Trước (deprecated)

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

Sau (hiện tại)

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

Bảng mapping nhanh

Pattern cũ	Pattern mới
Không có tool_configuration	MCPToolset không cần default_config hay configs
tool_configuration.enabled: false	default_config.enabled: false
tool_configuration.allowed_tools: [...]	default_config.enabled: false + bật tool trong configs

Lưu Ý Về Data Retention

MCP Connector không thuộc Zero Data Retention (ZDR). Dữ liệu trao đổi với MCP server, bao gồm tool definition và kết quả thực thi, được lưu trữ theo chính sách data retention tiêu chuẩn của Anthropic.