API 中的 MCP

MCP 連接器

Claude 的模型上下文協議 (MCP) 連接器功能讓您可以直接從 Messages API 連接到遠端 MCP 伺服器，無需單獨的 MCP 客戶端。

此功能需要 beta 標頭："anthropic-beta": "mcp-client-2025-04-04"

主要功能

直接 API 整合：無需實作 MCP 客戶端即可連接到 MCP 伺服器
工具呼叫支援：透過 Messages API 存取 MCP 工具
OAuth 驗證：支援 OAuth Bearer 權杖用於已驗證的伺服器
多個伺服器：在單一請求中連接到多個 MCP 伺服器

限制

在 MCP 規範的功能集中，目前僅支援工具呼叫。
伺服器必須透過 HTTP 公開暴露（支援 Streamable HTTP 和 SSE 傳輸）。本地 STDIO 伺服器無法直接連接。
MCP 連接器目前不支援 Amazon Bedrock 和 Google Vertex。

在 Messages API 中使用 MCP 連接器

要連接到遠端 MCP 伺服器，請在您的 Messages API 請求中包含 mcp_servers 參數：

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-04-04" \
  -d '{
    "model": "claude-sonnet-4-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"
      }
    ]
  }'

TypeScript

import { Anthropic } from '@anthropic-ai/sdk';

const anthropic = new Anthropic();

const response = await anthropic.beta.messages.create({
  model: "claude-sonnet-4-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",
    },
  ],
  betas: ["mcp-client-2025-04-04"],
});

Python

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1000,
    messages=[{
        "role": "user",
        "content": "What tools do you have available?"
    }],
    mcp_servers=[{
        "type": "url",
        "url": "https://mcp.example.com/sse",
        "name": "example-mcp",
        "authorization_token": "YOUR_TOKEN"
    }],
    betas=["mcp-client-2025-04-04"]
)

MCP 伺服器配置

mcp_servers 陣列中的每個 MCP 伺服器支援以下配置：

{
  "type": "url",
  "url": "https://example-server.modelcontextprotocol.io/sse",
  "name": "example-mcp",
  "tool_configuration": {
    "enabled": true,
    "allowed_tools": ["example_tool_1", "example_tool_2"]
  },
  "authorization_token": "YOUR_TOKEN"
}

欄位說明

屬性	類型	必需	說明
`type`	string	是	目前僅支援 "url"
`url`	string	是	MCP 伺服器的 URL。必須以 https:// 開頭
`name`	string	是	此 MCP 伺服器的唯一識別符。它將在 `mcp_tool_call` 區塊中用於識別伺服器並向模型消除工具歧義。
`tool_configuration`	object	否	配置工具使用
`tool_configuration.enabled`	boolean	否	是否啟用來自此伺服器的工具（預設：true）
`tool_configuration.allowed_tools`	array	否	限制允許的工具清單（預設情況下，允許所有工具）
`authorization_token`	string	否	如果 MCP 伺服器需要，則為 OAuth 授權權杖。請參閱 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 陣列中包含多個物件來連接到多個 MCP 伺服器：

{
  "model": "claude-sonnet-4-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"
    }
  ]
}

驗證

對於需要 OAuth 驗證的 MCP 伺服器，您需要取得存取權杖。MCP 連接器 beta 版支援在 MCP 伺服器定義中傳遞 authorization_token 參數。 API 消費者需要處理 OAuth 流程並在進行 API 呼叫之前取得存取權杖，以及根據需要刷新權杖。

取得用於測試的存取權杖

MCP 檢查器可以引導您完成取得用於測試目的的存取權杖的過程。

使用以下命令執行檢查器。您需要在機器上安裝 Node.js。
```
npx @modelcontextprotocol/inspector
```
在左側邊欄中，對於「傳輸類型」，選擇「SSE」或「Streamable HTTP」。
輸入 MCP 伺服器的 URL。
在右側區域中，在「需要配置驗證？」後點擊「開啟驗證設定」按鈕。
點擊「快速 OAuth 流程」並在 OAuth 畫面上授權。
按照檢查器「OAuth 流程進度」部分中的步驟，點擊「繼續」直到您到達「驗證完成」。
複製 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 規範中的授權部分。

API 中的 MCP

MCP 連接器

Claude 的模型上下文協議 (MCP) 連接器功能讓您可以直接從 Messages API 連接到遠端 MCP 伺服器，無需單獨的 MCP 客戶端。

此功能需要 beta 標頭："anthropic-beta": "mcp-client-2025-04-04"

主要功能

直接 API 整合：無需實作 MCP 客戶端即可連接到 MCP 伺服器
工具呼叫支援：透過 Messages API 存取 MCP 工具
OAuth 驗證：支援 OAuth Bearer 權杖用於已驗證的伺服器
多個伺服器：在單一請求中連接到多個 MCP 伺服器

限制

在 MCP 規範的功能集中，目前僅支援工具呼叫。
伺服器必須透過 HTTP 公開暴露（支援 Streamable HTTP 和 SSE 傳輸）。本地 STDIO 伺服器無法直接連接。
MCP 連接器目前不支援 Amazon Bedrock 和 Google Vertex。

在 Messages API 中使用 MCP 連接器

要連接到遠端 MCP 伺服器，請在您的 Messages API 請求中包含 mcp_servers 參數：

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-04-04" \
  -d '{
    "model": "claude-sonnet-4-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"
      }
    ]
  }'

TypeScript

import { Anthropic } from '@anthropic-ai/sdk';

const anthropic = new Anthropic();

const response = await anthropic.beta.messages.create({
  model: "claude-sonnet-4-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",
    },
  ],
  betas: ["mcp-client-2025-04-04"],
});

Python

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1000,
    messages=[{
        "role": "user",
        "content": "What tools do you have available?"
    }],
    mcp_servers=[{
        "type": "url",
        "url": "https://mcp.example.com/sse",
        "name": "example-mcp",
        "authorization_token": "YOUR_TOKEN"
    }],
    betas=["mcp-client-2025-04-04"]
)

MCP 伺服器配置

mcp_servers 陣列中的每個 MCP 伺服器支援以下配置：

{
  "type": "url",
  "url": "https://example-server.modelcontextprotocol.io/sse",
  "name": "example-mcp",
  "tool_configuration": {
    "enabled": true,
    "allowed_tools": ["example_tool_1", "example_tool_2"]
  },
  "authorization_token": "YOUR_TOKEN"
}

欄位說明

屬性	類型	必需	說明
`type`	string	是	目前僅支援 "url"
`url`	string	是	MCP 伺服器的 URL。必須以 https:// 開頭
`name`	string	是	此 MCP 伺服器的唯一識別符。它將在 `mcp_tool_call` 區塊中用於識別伺服器並向模型消除工具歧義。
`tool_configuration`	object	否	配置工具使用
`tool_configuration.enabled`	boolean	否	是否啟用來自此伺服器的工具（預設：true）
`tool_configuration.allowed_tools`	array	否	限制允許的工具清單（預設情況下，允許所有工具）
`authorization_token`	string	否	如果 MCP 伺服器需要，則為 OAuth 授權權杖。請參閱 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 陣列中包含多個物件來連接到多個 MCP 伺服器：

{
  "model": "claude-sonnet-4-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"
    }
  ]
}

驗證

取得用於測試的存取權杖

MCP 檢查器可以引導您完成取得用於測試目的的存取權杖的過程。

使用以下命令執行檢查器。您需要在機器上安裝 Node.js。
```
npx @modelcontextprotocol/inspector
```
在左側邊欄中，對於「傳輸類型」，選擇「SSE」或「Streamable HTTP」。
輸入 MCP 伺服器的 URL。
在右側區域中，在「需要配置驗證？」後點擊「開啟驗證設定」按鈕。
點擊「快速 OAuth 流程」並在 OAuth 畫面上授權。
按照檢查器「OAuth 流程進度」部分中的步驟，點擊「繼續」直到您到達「驗證完成」。
複製 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 規範中的授權部分。