MessagesMCP

MCP 連接器

Claude 的「Model Context Protocol」，即 MCP 連接器功能，讓您能夠直接從 Messages API 連接到遠端 MCP 伺服器，而無需單獨的 MCP 客戶端。

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

先前版本（mcp-client-2025-04-04）已棄用。請參閱已棄用版本：mcp-client-2025-04-04。

此功能不符合零資料保留（Zero Data Retention，ZDR）的資格。資料將依據該功能的標準保留政策進行保留。

主要功能

直接 API 整合：無需實作 MCP 客戶端即可連接到 MCP 伺服器
工具呼叫支援：透過 Messages API 存取 MCP 工具
彈性的工具設定：啟用所有工具、允許清單指定特定工具，或拒絕清單排除不需要的工具
個別工具設定：使用自訂設定來設定個別工具
OAuth 驗證：支援 OAuth Bearer 權杖以連接需要驗證的伺服器
多個伺服器：在單一請求中連接到多個 MCP 伺服器

Claude 何時使用 MCP 工具

一旦連接了 MCP 伺服器，當使用者的請求對應到某個工具所描述的功能時，Claude 就會呼叫該工具，無論是明確的請求（「在 Jira 中搜尋未解決的錯誤」）或隱含的請求（在已連接 Jira 伺服器的情況下詢問「是什麼阻礙了發布？」）。

對於關於已連接服務的一般知識問題，Claude 不會呼叫 MCP 工具。在已連接 Notion 伺服器的情況下詢問「Notion 資料庫如何運作？」會直接回答；而詢問「我的 Projects 資料庫裡有什麼？」則會觸發工具。

您可以透過系統提示來引導 Claude 呼叫 MCP 工具的積極程度。請參閱 Claude 何時使用工具以取得一般指引和範例措辭。

限制

在 MCP 規範的功能集中，目前僅支援工具呼叫。
伺服器必須透過 HTTP 公開存取（支援 Streamable HTTP 和 SSE 傳輸方式）。本機 STDIO 伺服器無法直接連接。
MCP 連接器可在 Claude API、AWS 上的 Claude Platform 和 Microsoft Foundry 上使用。目前在 Amazon Bedrock 或 Vertex AI 上尚不可用。

在 Messages API 中使用 MCP 連接器

MCP 連接器使用兩個元件：

MCP 伺服器定義（mcp_servers 陣列）：定義伺服器連線詳細資訊（URL、驗證）
MCP 工具集（tools 陣列）：設定要啟用哪些工具以及如何設定它們

基本範例

此範例使用預設設定啟用 MCP 伺服器的所有工具：

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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 伺服器設定

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，工具描述一開始不會傳送給模型。與工具搜尋工具搭配使用。

如需 Anthropic 提供的工具完整目錄以及 defer_loading 等選用屬性，請參閱工具參考。如需在大型工具集中進行搜尋，請參閱工具搜尋工具。

設定合併

設定值依以下優先順序合併（由高至低）：

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

當有許多工具可用時，Claude 會根據工具名稱和描述進行選擇。清晰、具體的工具描述可提高選擇準確度。對於大型工具集（跨多個伺服器的數十個工具），請考慮搭配工具搜尋工具啟用 defer_loading，以便每次查詢僅顯示相關工具。

驗證

對於需要 OAuth 驗證的 MCP 伺服器，您需要取得存取權杖。MCP 連接器 beta 版支援在 MCP 伺服器定義中傳遞 authorization_token 參數。 API 使用者應在進行 API 呼叫之前處理 OAuth 流程並取得存取權杖，並視需要重新整理權杖。

取得用於測試的存取權杖

MCP inspector 可以引導您完成取得測試用存取權杖的流程。

使用以下指令執行 inspector。您的機器上需要安裝 Node.js。
```
npx @modelcontextprotocol/inspector
```
在左側邊欄中，針對「Transport type」選擇「SSE」或「Streamable HTTP」。
輸入 MCP 伺服器的 URL。
在右側區域中，點擊「Need to configure authentication?」後方的「Open Auth Settings」按鈕。
點擊「Quick OAuth Flow」並在 OAuth 畫面上進行授權。
依照 inspector 中「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 輔助函式

如果您管理自己的 MCP 客戶端連線（例如，使用本機 stdio 伺服器、MCP 提示或 MCP 資源），SDK 提供了輔助函式，可在 MCP 類型和 Claude API 類型之間進行轉換。這樣在搭配使用 MCP SDK（例如 TypeScript MCP SDK）與 Anthropic SDK 時，就無需手動撰寫轉換程式碼。

這些輔助函式可在 Python、TypeScript、Java、Go、Ruby 和 PHP SDK 中使用。目前尚未在 C# SDK 中提供。本節中的範例使用 TypeScript；在其他語言中，請從以下位置匯入對應的輔助函式：

Python： anthropic.lib.tools.mcp（使用 pip install anthropic[mcp] 安裝）
Java： anthropic-java-mcp 模組中的 com.anthropic.mcp.BetaMcp
Go： github.com/anthropics/anthropic-sdk-go/mcp
Ruby： Anthropic::Mcp（需要 mcp gem）
PHP： Anthropic\Lib\Tools\BetaMcp

當您擁有可透過 URL 存取的遠端伺服器且僅需要工具支援時，請使用 mcp_servers API 參數。當您需要本機伺服器、提示、資源，或需要透過基礎 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 { 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-8",
  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-8",
  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-8",
  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) });

錯誤處理

如果 Claude API 不支援某個 MCP 值，轉換函式會拋出 UnsupportedMCPValueError。這可能發生在不支援的內容類型、MIME 類型或非 HTTP 資源連結的情況下。

批次請求

您可以在 Message Batches API 請求中包含 mcp_servers。透過 Batches API 進行的 MCP 工具呼叫，其定價與一般 Messages API 請求中的相同。

資料保留

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-8",
  "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-8",
  "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?

MessagesMCP

MCP 連接器

Claude 的「Model Context Protocol」，即 MCP 連接器功能，讓您能夠直接從 Messages API 連接到遠端 MCP 伺服器，而無需單獨的 MCP 客戶端。

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

先前版本（mcp-client-2025-04-04）已棄用。請參閱已棄用版本：mcp-client-2025-04-04。

此功能不符合零資料保留（Zero Data Retention，ZDR）的資格。資料將依據該功能的標準保留政策進行保留。

主要功能

直接 API 整合：無需實作 MCP 客戶端即可連接到 MCP 伺服器
工具呼叫支援：透過 Messages API 存取 MCP 工具
彈性的工具設定：啟用所有工具、允許清單指定特定工具，或拒絕清單排除不需要的工具
個別工具設定：使用自訂設定來設定個別工具
OAuth 驗證：支援 OAuth Bearer 權杖以連接需要驗證的伺服器
多個伺服器：在單一請求中連接到多個 MCP 伺服器

Claude 何時使用 MCP 工具

您可以透過系統提示來引導 Claude 呼叫 MCP 工具的積極程度。請參閱 Claude 何時使用工具以取得一般指引和範例措辭。

限制

在 MCP 規範的功能集中，目前僅支援工具呼叫。
伺服器必須透過 HTTP 公開存取（支援 Streamable HTTP 和 SSE 傳輸方式）。本機 STDIO 伺服器無法直接連接。
MCP 連接器可在 Claude API、AWS 上的 Claude Platform 和 Microsoft Foundry 上使用。目前在 Amazon Bedrock 或 Vertex AI 上尚不可用。

在 Messages API 中使用 MCP 連接器

MCP 連接器使用兩個元件：

MCP 伺服器定義（mcp_servers 陣列）：定義伺服器連線詳細資訊（URL、驗證）
MCP 工具集（tools 陣列）：設定要啟用哪些工具以及如何設定它們

基本範例

此範例使用預設設定啟用 MCP 伺服器的所有工具：

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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 伺服器設定

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，工具描述一開始不會傳送給模型。與工具搜尋工具搭配使用。

如需 Anthropic 提供的工具完整目錄以及 defer_loading 等選用屬性，請參閱工具參考。如需在大型工具集中進行搜尋，請參閱工具搜尋工具。

設定合併

設定值依以下優先順序合併（由高至低）：

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-8",
  "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 inspector 可以引導您完成取得測試用存取權杖的流程。

使用以下指令執行 inspector。您的機器上需要安裝 Node.js。
```
npx @modelcontextprotocol/inspector
```
在左側邊欄中，針對「Transport type」選擇「SSE」或「Streamable HTTP」。
輸入 MCP 伺服器的 URL。
在右側區域中，點擊「Need to configure authentication?」後方的「Open Auth Settings」按鈕。
點擊「Quick OAuth Flow」並在 OAuth 畫面上進行授權。
依照 inspector 中「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 輔助函式

Python： anthropic.lib.tools.mcp（使用 pip install anthropic[mcp] 安裝）
Java： anthropic-java-mcp 模組中的 com.anthropic.mcp.BetaMcp
Go： github.com/anthropics/anthropic-sdk-go/mcp
Ruby： Anthropic::Mcp（需要 mcp gem）
PHP： Anthropic\Lib\Tools\BetaMcp

安裝

安裝 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 { 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-8",
  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-8",
  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-8",
  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) });

錯誤處理

如果 Claude API 不支援某個 MCP 值，轉換函式會拋出 UnsupportedMCPValueError。這可能發生在不支援的內容類型、MIME 類型或非 HTTP 資源連結的情況下。

批次請求

您可以在 Message Batches API 請求中包含 mcp_servers。透過 Batches API 進行的 MCP 工具呼叫，其定價與一般 Messages API 請求中的相同。

資料保留

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-8",
  "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-8",
  "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?

主要功能

Claude 何時使用 MCP 工具

限制

在 Messages API 中使用 MCP 連接器

基本範例

MCP 伺服器設定

欄位說明

MCP 工具集設定

基本結構

欄位說明

工具設定選項

設定合併

常見設定模式

使用預設設定啟用所有工具

允許清單：僅啟用特定工具

拒絕清單：停用特定工具

混合：允許清單搭配個別工具設定

驗證規則

回應內容類型

MCP 工具使用區塊

MCP 工具結果區塊

多個 MCP 伺服器

驗證

取得用於測試的存取權杖

使用存取權杖

客戶端 MCP 輔助函式

安裝

可用的輔助函式

使用 MCP 工具

使用 MCP 提示

使用 MCP 資源

錯誤處理

批次請求

資料保留

遷移指南

主要變更

遷移步驟

常見遷移模式

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

已棄用的欄位說明

主要功能

Claude 何時使用 MCP 工具

限制

在 Messages API 中使用 MCP 連接器

基本範例

MCP 伺服器設定

欄位說明

MCP 工具集設定

基本結構

欄位說明

工具設定選項

設定合併

常見設定模式

使用預設設定啟用所有工具

允許清單：僅啟用特定工具

拒絕清單：停用特定工具

混合：允許清單搭配個別工具設定

驗證規則

回應內容類型

MCP 工具使用區塊

MCP 工具結果區塊

多個 MCP 伺服器

驗證

取得用於測試的存取權杖

使用存取權杖

客戶端 MCP 輔助函式

安裝

可用的輔助函式

使用 MCP 工具

使用 MCP 提示

使用 MCP 資源

錯誤處理

批次請求

資料保留

遷移指南

主要變更

遷移步驟

常見遷移模式

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

已棄用的欄位說明

主要功能

Claude 何時使用 MCP 工具

限制

在 Messages API 中使用 MCP 連接器

基本範例

MCP 伺服器設定

欄位說明

MCP 工具集設定

基本結構

欄位說明

工具設定選項

設定合併

常見設定模式

使用預設設定啟用所有工具

允許清單：僅啟用特定工具

拒絕清單：停用特定工具

混合：允許清單搭配個別工具設定

驗證規則

回應內容類型

MCP 工具使用區塊

MCP 工具結果區塊

多個 MCP 伺服器

驗證

取得用於測試的存取權杖

使用存取權杖

客戶端 MCP 輔助函式

安裝

可用的輔助函式

使用 MCP 工具

使用 MCP 提示

使用 MCP 資源

錯誤處理

批次請求

資料保留

遷移指南

主要變更

遷移步驟

常見遷移模式

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

已棄用的欄位說明

主要功能

Claude 何時使用 MCP 工具

限制

在 Messages API 中使用 MCP 連接器

基本範例

MCP 伺服器設定

欄位說明

MCP 工具集設定

基本結構

欄位說明

工具設定選項

設定合併

常見設定模式

使用預設設定啟用所有工具

允許清單：僅啟用特定工具

拒絕清單：停用特定工具

混合：允許清單搭配個別工具設定

驗證規則

回應內容類型

MCP 工具使用區塊

MCP 工具結果區塊

多個 MCP 伺服器

驗證

取得用於測試的存取權杖

使用存取權杖

客戶端 MCP 輔助函式

安裝

可用的輔助函式

使用 MCP 工具

使用 MCP 提示

使用 MCP 資源

錯誤處理

批次請求

資料保留

遷移指南

主要變更

遷移步驟

常見遷移模式

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

已棄用的欄位說明