MCP 連接器

Claude 的「Model Context Protocol」，即 MCP 連接器（connector）功能，讓您無需另外的 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 連接器使用兩個元件：

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

基本範例

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5-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"
}

欄位說明

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

欄位說明

使用 mcp-client-2026-09-15 beta 標頭時，MCPToolset 也接受 tools，即伺服器工具清單的固定副本。請參閱固定 MCP 伺服器的工具清單。

工具設定選項

每個工具（無論是在 default_config 或 configs 中設定）皆支援下列欄位：

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

設定合併

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

1. configs 中的工具專屬設定
2. 集合層級的 default_config
3. 系統預設值

範例：

{
  "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 伺服器的工具清單（beta）

MCP 伺服器隨時可能變更其工具。mcp-client-2026-09-15 beta 標頭會記錄每個伺服器傳回的工具清單，並讓您將其固定，如此一來，變更工具的伺服器就不會在對話進行到一半時改變 Claude 所看到的內容。它包含 mcp-client-2025-11-20 的所有功能，因此請以它取代該標頭傳送。此功能可在 Claude API 上使用。

當 API 在產生回應時向 MCP 伺服器請求其工具，回應會以該伺服器的 mcp_tool_listing 區塊開頭，每個被請求的伺服器各有一個區塊：

{
  "type": "mcp_tool_listing",
  "mcp_server_name": "example-mcp",
  "tools": [
    {
      "name": "echo",
      "description": "Returns the text it receives.",
      "input_schema": {
        "type": "object",
        "properties": { "text": { "type": "string" } },
        "required": ["text"]
      }
    }
  ]
}

如果您的程式碼會讀取 content[0]，請略過這些區塊。請原封不動地傳回助理訊息（包含 mcp_tool_listing 區塊），並在每個帶有此類區塊的請求中持續傳送 mcp-client-2026-09-15。之後的請求便會使用該伺服器已記錄的清單，而不會再次向伺服器請求。

若要自行固定清單，請將區塊的 tools 複製到該伺服器 MCPToolset 的 tools 欄位中。API 便不會向伺服器請求其工具，而工具集的工具就會恰好是這些項目，並套用 default_config 和 configs：

{
  "type": "mcp_toolset",
  "mcp_server_name": "example-mcp",
  "tools": [
    {
      "name": "echo",
      "description": "Returns the text it receives.",
      "input_schema": {
        "type": "object",
        "properties": { "text": { "type": "string" } },
        "required": ["text"]
      }
    }
  ]
}

tools 中的每個項目都包含伺服器所列出的工具 name（不含伺服器名稱）、其 description 以及其 input_schema。

以下範例會以未固定的工具集傳送一個請求，將傳回的清單複製到工具集的 tools 欄位中，然後再次傳送請求。第二個回應沒有 mcp_tool_listing 區塊，因為 API 不會向伺服器請求：

from anthropic.types.beta import (
    BetaMessageParam,
    BetaRequestMCPServerURLDefinitionParam,
)

client = anthropic.Anthropic()

mcp_servers: list[BetaRequestMCPServerURLDefinitionParam] = [
    {
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse",
        "name": "example-mcp",
        "authorization_token": "YOUR_TOKEN",
    },
]
messages: list[BetaMessageParam] = [
    {"role": "user", "content": "What tools do you have available?"},
]

# 第一次請求：toolset 尚未固定，因此 API 會向伺服器查詢
# 其工具，而回應會以 mcp_tool_listing 區塊開頭。
first = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    betas=["mcp-client-2026-09-15"],
    mcp_servers=mcp_servers,
    tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
    messages=messages,
)

listing = next(block for block in first.content if block.type == "mcp_tool_listing")
print([tool.name for tool in listing.tools])

# 固定清單：將該區塊的 tools 複製到 toolset 中。API 會使用
# 完全相同的這些項目，且不會再次查詢伺服器。
second = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    betas=["mcp-client-2026-09-15"],
    mcp_servers=mcp_servers,
    tools=[
        {
            "type": "mcp_toolset",
            "mcp_server_name": "example-mcp",
            "tools": [
                {
                    "name": tool.name,
                    "description": tool.description,
                    "input_schema": tool.input_schema,
                }
                for tool in listing.tools
            ],
        },
    ],
    messages=messages,
)

# 使用已固定的 toolset 時，回應中不會有 mcp_tool_listing 區塊。
print([block.type for block in second.content])

若同時使用 inline-tools-2026-09-15 beta 標頭，您可以在對話進行中新增 MCP 伺服器。請參閱在對話中途新增 MCP 伺服器。

多個 MCP 伺服器

您可以在 mcp_servers 中包含多個伺服器定義，並在 tools 陣列中為每個伺服器包含對應的 MCPToolset，以連接至多個 MCP 伺服器：

{
  "model": "claude-opus-5-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 可引導您完成取得測試用存取權杖的流程。

1. 使用下列指令執行 inspector。您的機器上需要安裝 Node.js。

   npx @modelcontextprotocol/inspector

   

2. 在左側的側邊欄中，針對 Transport type，選擇 SSE 或 Streamable HTTP。

3. 輸入 MCP 伺服器的 URL。

4. 在右側區域中，點擊 Need to configure authentication? 後方的 Open Auth Settings。

5. 點擊 Quick OAuth Flow 並在 OAuth 畫面上授權。

6. 依照 inspector 中 OAuth Flow Progress 區段的步驟，並點擊 Continue，直到到達 Authentication complete。

7. 複製 access_token 值。

8. 將其貼到 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：

pip install "anthropic[mcp]"

可用的輔助函式

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

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

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

使用 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-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-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,
)

# 作為訊息中的內容區塊
resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
response = await client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                mcp_resource_to_content(resource),
                {"type": "text", "text": "Summarize this document"},
            ],
        }
    ],
)
print(response)

# 作為檔案上傳
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)

錯誤處理

若某個 MCP 值不受 Claude API 支援，轉換函式會拋出 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 測試版標頭，請依照本指南遷移至新版本。

主要變更

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

遷移步驟

之前（已棄用）：

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

常見遷移模式

已棄用版本：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"]
      }
    }
  ]
}

已棄用欄位說明

Compatibility