API 中的 MCP

MCP 連接器

透過 Messages API 直接連接到遠端 MCP 伺服器，無需獨立的 MCP 客戶端。

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

目前版本：此功能需要 beta 標頭："anthropic-beta": "mcp-client-2025-11-20"

舊版本（mcp-client-2025-04-04）已棄用。請參閱下方的棄用版本文件。

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

主要功能

直接 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 連接器使用兩個元件：

MCP 伺服器定義（mcp_servers 陣列）：定義伺服器連接詳細資訊（URL、驗證）
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-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"
      }
    ]
  }'

MCP 伺服器配置

mcp_servers 陣列中的每個 MCP 伺服器定義連接詳細資訊：

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

欄位說明

屬性	類型	必填	說明
`type`	string	是	目前僅支援 "url"
`url`	string	是	MCP 伺服器的 URL。必須以 https:// 開頭
`name`	string	是	此 MCP 伺服器的唯一識別碼。必須由 `tools` 陣列中的恰好一個 MCPToolset 引用。
`authorization_token`	string	否	如果 MCP 伺服器需要，則提供 OAuth 授權令牌。請參閱 MCP 規範。

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

欄位說明

屬性	類型	必填	說明
`type`	string	是	必須為 "mcp_toolset"
`mcp_server_name`	string	是	必須與 `mcp_servers` 陣列中定義的伺服器名稱相符
`default_config`	object	否	套用於此集合中所有工具的預設配置。`configs` 中的個別工具配置將覆蓋這些預設值。
`configs`	object	否	每個工具的配置覆蓋。鍵為工具名稱，值為配置物件。
`cache_control`	object	否	此工具集的快取中斷點配置

工具配置選項

每個工具（無論是在 default_config 還是在 configs 中配置）都支援以下欄位：

屬性	類型	預設值	說明
`enabled`	boolean	`true`	此工具是否已啟用
`defer_loading`	boolean	`false`	若為 true，工具描述最初不會傳送給模型。與工具搜尋工具搭配使用。

配置合併

配置值按以下優先順序合併（從高到低）：

configs 中的工具特定設定
集合層級的 default_config
系統預設值

範例：

{
  "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-6",
  "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 檢查器可以引導您完成取得測試用存取令牌的過程。

使用以下命令執行檢查器。您需要在機器上安裝 Node.js。
```
npx @modelcontextprotocol/inspector
```
在左側邊欄中，對於「Transport type」，選擇「SSE」或「Streamable HTTP」。
輸入 MCP 伺服器的 URL。
在右側區域，點擊「Need to configure authentication?」後的「Open Auth Settings」按鈕。
點擊「Quick OAuth Flow」並在 OAuth 畫面上授權。
按照檢查器「OAuth Flow Progress」部分的步驟操作，並點擊「Continue」直到到達「Authentication complete」。
複製 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 規範中的授權部分。

客戶端 MCP 輔助工具（TypeScript）

如果您自行管理 MCP 客戶端連接（例如，使用本地 stdio 伺服器、MCP 提示或 MCP 資源），TypeScript SDK 提供了在 MCP 類型和 Claude API 類型之間轉換的輔助函式。這消除了在 MCP SDK 與 Anthropic SDK 一起使用時的手動轉換程式碼。

這些輔助工具目前僅在 TypeScript SDK 中提供。

當您有可透過 URL 存取的遠端伺服器且只需要工具支援時，請使用 mcp_servers API 參數。如果您使用 Agent SDK，MCP 連接將自動管理。當您需要本地伺服器、提示、資源，或需要對基礎 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";

輔助工具	說明
`mcpTools(tools, mcpClient)`	將 MCP 工具轉換為 Claude API 工具，以與 `client.beta.messages.toolRunner()` 搭配使用
`mcpMessages(messages)`	將 MCP 提示訊息轉換為 Claude API 訊息格式
`mcpResourceToContent(resource)`	將 MCP 資源轉換為 Claude API 內容區塊
`mcpResourceToFile(resource)`	將 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 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)
});

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

使用 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-sonnet-4-6",
  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 標頭，請按照本指南遷移到新版本。

主要變更

新的 beta 標頭：從 mcp-client-2025-04-04 更改為 mcp-client-2025-11-20
工具配置已移動：工具配置現在作為 MCPToolset 物件位於 tools 陣列中，而不是在 MCP 伺服器定義中
更靈活的配置：新模式支援允許清單、拒絕清單和每個工具的配置

遷移步驟

之前（已棄用）：

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

常見遷移模式

舊模式	新模式
無 `tool_configuration`（所有工具已啟用）	無 `default_config` 或 `configs` 的 MCPToolset
`tool_configuration.enabled: false`	帶有 `default_config.enabled: false` 的 MCPToolset
`tool_configuration.allowed_tools: [...]`	帶有 `default_config.enabled: false` 且在 `configs` 中啟用特定工具的 MCPToolset

棄用版本：mcp-client-2025-04-04

此版本已棄用。請使用上方的遷移指南遷移到 mcp-client-2025-11-20。

舊版本的 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"]
      }
    }
  ]
}

棄用欄位說明

屬性	類型	說明
`tool_configuration`	object	已棄用：請改用 `tools` 陣列中的 MCPToolset
`tool_configuration.enabled`	boolean	已棄用：請改用 MCPToolset 中的 `default_config.enabled`
`tool_configuration.allowed_tools`	array	已棄用：請改用 MCPToolset 中帶有 `configs` 的允許清單模式

Was this page helpful?

API 中的 MCP

MCP 連接器

透過 Messages API 直接連接到遠端 MCP 伺服器，無需獨立的 MCP 客戶端。

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

目前版本：此功能需要 beta 標頭："anthropic-beta": "mcp-client-2025-11-20"

舊版本（mcp-client-2025-04-04）已棄用。請參閱下方的棄用版本文件。

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

主要功能

直接 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 連接器使用兩個元件：

MCP 伺服器定義（mcp_servers 陣列）：定義伺服器連接詳細資訊（URL、驗證）
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-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"
      }
    ]
  }'

MCP 伺服器配置

mcp_servers 陣列中的每個 MCP 伺服器定義連接詳細資訊：

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

欄位說明

屬性	類型	必填	說明
`type`	string	是	目前僅支援 "url"
`url`	string	是	MCP 伺服器的 URL。必須以 https:// 開頭
`name`	string	是	此 MCP 伺服器的唯一識別碼。必須由 `tools` 陣列中的恰好一個 MCPToolset 引用。
`authorization_token`	string	否	如果 MCP 伺服器需要，則提供 OAuth 授權令牌。請參閱 MCP 規範。

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

欄位說明

屬性	類型	必填	說明
`type`	string	是	必須為 "mcp_toolset"
`mcp_server_name`	string	是	必須與 `mcp_servers` 陣列中定義的伺服器名稱相符
`default_config`	object	否	套用於此集合中所有工具的預設配置。`configs` 中的個別工具配置將覆蓋這些預設值。
`configs`	object	否	每個工具的配置覆蓋。鍵為工具名稱，值為配置物件。
`cache_control`	object	否	此工具集的快取中斷點配置

工具配置選項

每個工具（無論是在 default_config 還是在 configs 中配置）都支援以下欄位：

屬性	類型	預設值	說明
`enabled`	boolean	`true`	此工具是否已啟用
`defer_loading`	boolean	`false`	若為 true，工具描述最初不會傳送給模型。與工具搜尋工具搭配使用。

配置合併

配置值按以下優先順序合併（從高到低）：

configs 中的工具特定設定
集合層級的 default_config
系統預設值

範例：

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

驗證

取得測試用存取令牌

MCP 檢查器可以引導您完成取得測試用存取令牌的過程。

使用以下命令執行檢查器。您需要在機器上安裝 Node.js。
```
npx @modelcontextprotocol/inspector
```
在左側邊欄中，對於「Transport type」，選擇「SSE」或「Streamable HTTP」。
輸入 MCP 伺服器的 URL。
在右側區域，點擊「Need to configure authentication?」後的「Open Auth Settings」按鈕。
點擊「Quick OAuth Flow」並在 OAuth 畫面上授權。
按照檢查器「OAuth Flow Progress」部分的步驟操作，並點擊「Continue」直到到達「Authentication complete」。
複製 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 規範中的授權部分。

客戶端 MCP 輔助工具（TypeScript）

這些輔助工具目前僅在 TypeScript 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";

輔助工具	說明
`mcpTools(tools, mcpClient)`	將 MCP 工具轉換為 Claude API 工具，以與 `client.beta.messages.toolRunner()` 搭配使用
`mcpMessages(messages)`	將 MCP 提示訊息轉換為 Claude API 訊息格式
`mcpResourceToContent(resource)`	將 MCP 資源轉換為 Claude API 內容區塊
`mcpResourceToFile(resource)`	將 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 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)
});

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

使用 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-sonnet-4-6",
  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 標頭，請按照本指南遷移到新版本。

主要變更

新的 beta 標頭：從 mcp-client-2025-04-04 更改為 mcp-client-2025-11-20
工具配置已移動：工具配置現在作為 MCPToolset 物件位於 tools 陣列中，而不是在 MCP 伺服器定義中
更靈活的配置：新模式支援允許清單、拒絕清單和每個工具的配置

遷移步驟

之前（已棄用）：

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

常見遷移模式

舊模式	新模式
無 `tool_configuration`（所有工具已啟用）	無 `default_config` 或 `configs` 的 MCPToolset
`tool_configuration.enabled: false`	帶有 `default_config.enabled: false` 的 MCPToolset
`tool_configuration.allowed_tools: [...]`	帶有 `default_config.enabled: false` 且在 `configs` 中啟用特定工具的 MCPToolset

棄用版本：mcp-client-2025-04-04

此版本已棄用。請使用上方的遷移指南遷移到 mcp-client-2025-11-20。

舊版本的 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"]
      }
    }
  ]
}

棄用欄位說明

屬性	類型	說明
`tool_configuration`	object	已棄用：請改用 `tools` 陣列中的 MCPToolset
`tool_configuration.enabled`	boolean	已棄用：請改用 MCPToolset 中的 `default_config.enabled`
`tool_configuration.allowed_tools`	array	已棄用：請改用 MCPToolset 中帶有 `configs` 的允許清單模式

Was this page helpful?