MessagesMCP

MCP 連接器

無需 MCP 用戶端即可直接從 Messages API 連接到遠端 MCP 伺服器，並對個別工具進行允許清單、拒絕清單或設定。

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

主要功能

直接 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 伺服器無法直接連接。

在 Messages API 中使用 MCP 連接器

MCP 連接器使用兩個元件：

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

基本範例

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-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",
        }
    ],
    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-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"
    }
  ],
  "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 連接器測試版支援在 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 一起使用時，這可消除手動轉換程式碼。

安裝

安裝 Anthropic SDK 和 MCP SDK：

MCP 輔助函式包含在 mcp 額外套件中，需要 Python 3.10 或更高版本：

pip install "anthropic[mcp]"

可用的輔助函式

匯入適用於您語言的輔助函式：

from anthropic.lib.tools.mcp import (
    async_mcp_tool,
    mcp_message,
    mcp_resource_to_content,
    mcp_resource_to_file,
)

輔助函式名稱和確切簽章遵循各語言的慣例；下表顯示 TypeScript 形式：

輔助函式	說明
`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 的工具執行器使用，該執行器會自動處理工具執行：

from anthropic.lib.tools.mcp import async_mcp_tool
from mcp import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

client = AsyncAnthropic()


async def main() -> None:
    # 連線到 MCP 伺服器
    server_params = StdioServerParameters(command="mcp-server")
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as mcp_client:
            await mcp_client.initialize()

            # 列出工具並將其轉換為 Claude API 格式
            tools_result = await mcp_client.list_tools()
            runner = client.beta.messages.tool_runner(
                model="claude-opus-5",
                max_tokens=1024,
                messages=[
                    {"role": "user", "content": "What tools do you have available?"},
                ],
                tools=[async_mcp_tool(tool, mcp_client) for tool in tools_result.tools],
            )

            final_message = await runner.until_done()
            print(final_message)


asyncio.run(main())

使用 MCP 提示

將 MCP 提示訊息轉換為 Claude API 訊息格式：

from anthropic.lib.tools.mcp import mcp_message

prompt = await mcp_client.get_prompt(name="my-prompt")
response = await client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[mcp_message(message) for message in prompt.messages],
)

print(response)

使用 MCP 資源

將 MCP 資源轉換為內容區塊以包含在訊息中，或轉換為用於上傳的檔案物件：

from anthropic.lib.tools.mcp import (
    mcp_resource_to_content,
    mcp_resource_to_file,
)

# As a content block in a message
resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
response = await client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                mcp_resource_to_content(resource),
                {"type": "text", "text": "Summarize this document"},
            ],
        }
    ],
)
print(response)

# As a file upload
file_resource = await mcp_client.read_resource(
    uri="file:///path/to/data.json",
)
uploaded = await client.files.upload(
    file=mcp_resource_to_file(file_resource),
)
print(uploaded.id)

錯誤處理

如果 Claude API 不支援某個 MCP 值，轉換函式會拋出 UnsupportedMCPValueError（在 Go 中，輔助函式會回傳 UnsupportedValueError；在 Java 和 C# 中，會拋出 AnthropicInvalidDataException）。這可能發生在不支援的內容類型、MIME 類型或資源連結上（在轉換之前，請使用您的 MCP 用戶端解析資源連結）。

批次請求

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

資料保留

MCP 連接器不在 ZDR 協議的涵蓋範圍內。與 MCP 伺服器交換的資料（包括工具定義和執行結果）會依據 Anthropic 的標準資料保留政策進行保留。

如需所有功能的 ZDR 資格資訊，請參閱 API 與資料保留。

遷移指南

如果您正在使用已棄用的 mcp-client-2025-04-04 測試版標頭，請依照本指南遷移至新版本。

主要變更

新的測試版標頭：從 mcp-client-2025-04-04 變更為 mcp-client-2025-11-20
工具設定已移動：工具設定現在以 MCPToolset 物件的形式位於 tools 陣列中，而非 MCP 伺服器定義中
更彈性的設定：新模式支援允許清單、拒絕清單和個別工具設定

遷移步驟

之前（已棄用）：

{
  "model": "claude-opus-5",
  "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-5",
  "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 連接器的先前版本直接在 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` 的允許清單模式

Compatibility

Supported platforms	Claude APIBeta Claude Platform on AWSBeta Microsoft Foundry¹Beta

在 Microsoft Foundry 上，MCP 連接器需要 Hosted on Anthropic 部署。 ↩

Was this page helpful?

MessagesMCP

MCP 連接器

無需 MCP 用戶端即可直接從 Messages API 連接到遠端 MCP 伺服器，並對個別工具進行允許清單、拒絕清單或設定。

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

主要功能

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

Claude 何時使用 MCP 工具

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

限制

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

在 Messages API 中使用 MCP 連接器

MCP 連接器使用兩個元件：

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

基本範例

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-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",
        }
    ],
    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-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"
    }
  ],
  "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 輔助函式

安裝

安裝 Anthropic SDK 和 MCP SDK：

MCP 輔助函式包含在 mcp 額外套件中，需要 Python 3.10 或更高版本：

pip install "anthropic[mcp]"

可用的輔助函式

匯入適用於您語言的輔助函式：

from anthropic.lib.tools.mcp import (
    async_mcp_tool,
    mcp_message,
    mcp_resource_to_content,
    mcp_resource_to_file,
)

輔助函式名稱和確切簽章遵循各語言的慣例；下表顯示 TypeScript 形式：

輔助函式	說明
`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 的工具執行器使用，該執行器會自動處理工具執行：

from anthropic.lib.tools.mcp import async_mcp_tool
from mcp import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

client = AsyncAnthropic()


async def main() -> None:
    # 連線到 MCP 伺服器
    server_params = StdioServerParameters(command="mcp-server")
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as mcp_client:
            await mcp_client.initialize()

            # 列出工具並將其轉換為 Claude API 格式
            tools_result = await mcp_client.list_tools()
            runner = client.beta.messages.tool_runner(
                model="claude-opus-5",
                max_tokens=1024,
                messages=[
                    {"role": "user", "content": "What tools do you have available?"},
                ],
                tools=[async_mcp_tool(tool, mcp_client) for tool in tools_result.tools],
            )

            final_message = await runner.until_done()
            print(final_message)


asyncio.run(main())

使用 MCP 提示

將 MCP 提示訊息轉換為 Claude API 訊息格式：

from anthropic.lib.tools.mcp import mcp_message

prompt = await mcp_client.get_prompt(name="my-prompt")
response = await client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[mcp_message(message) for message in prompt.messages],
)

print(response)

使用 MCP 資源

將 MCP 資源轉換為內容區塊以包含在訊息中，或轉換為用於上傳的檔案物件：

from anthropic.lib.tools.mcp import (
    mcp_resource_to_content,
    mcp_resource_to_file,
)

# As a content block in a message
resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
response = await client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                mcp_resource_to_content(resource),
                {"type": "text", "text": "Summarize this document"},
            ],
        }
    ],
)
print(response)

# As a file upload
file_resource = await mcp_client.read_resource(
    uri="file:///path/to/data.json",
)
uploaded = await client.files.upload(
    file=mcp_resource_to_file(file_resource),
)
print(uploaded.id)

錯誤處理

批次請求

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

資料保留

MCP 連接器不在 ZDR 協議的涵蓋範圍內。與 MCP 伺服器交換的資料（包括工具定義和執行結果）會依據 Anthropic 的標準資料保留政策進行保留。

如需所有功能的 ZDR 資格資訊，請參閱 API 與資料保留。

遷移指南

如果您正在使用已棄用的 mcp-client-2025-04-04 測試版標頭，請依照本指南遷移至新版本。

主要變更

新的測試版標頭：從 mcp-client-2025-04-04 變更為 mcp-client-2025-11-20
工具設定已移動：工具設定現在以 MCPToolset 物件的形式位於 tools 陣列中，而非 MCP 伺服器定義中
更彈性的設定：新模式支援允許清單、拒絕清單和個別工具設定

遷移步驟

之前（已棄用）：

{
  "model": "claude-opus-5",
  "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-5",
  "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 連接器的先前版本直接在 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` 的允許清單模式

Compatibility

Supported platforms	Claude APIBeta Claude Platform on AWSBeta Microsoft Foundry¹Beta

在 Microsoft Foundry 上，MCP 連接器需要 Hosted on Anthropic 部署。 ↩

Was this page helpful?

主要功能

Claude 何時使用 MCP 工具

限制

在 Messages API 中使用 MCP 連接器

基本範例

MCP 伺服器設定

欄位說明

MCP 工具集設定

基本結構

欄位說明

工具設定選項

設定合併

常見設定模式

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

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

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

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

驗證規則

回應內容類型

MCP 工具使用區塊

MCP 工具結果區塊

多個 MCP 伺服器

驗證

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

使用存取權杖

用戶端 MCP 輔助函式

安裝

可用的輔助函式

使用 MCP 工具

使用 MCP 提示

使用 MCP 資源

錯誤處理

批次請求

資料保留

遷移指南

主要變更

遷移步驟

常見遷移模式

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

已棄用的欄位說明

Compatibility

主要功能

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

已棄用的欄位說明