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 伺服器無法直接連接。
• MCP 連接器可在 Claude API、Claude Platform on AWS 和 Microsoft Foundry 上使用。在 Microsoft Foundry 上，MCP 連接器需要 Hosted on Anthropic 部署。目前在 Amazon Bedrock 或 Google Cloud 上尚不可用。



在 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",
    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
    }
  }
}



欄位說明



工具設定選項

每個工具（無論是在 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 伺服器

您可以透過在 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 連接器 beta 支援在 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",
                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,
)

# 作為訊息中的內容區塊
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)

# 作為檔案上傳
file_resource = await mcp_client.read_resource(
    uri="file:///path/to/data.json",
)
uploaded = await client.beta.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 beta 標頭，請依照本指南遷移到新版本。



主要變更

1. 新的 beta 標頭：從 mcp-client-2025-04-04 變更為 mcp-client-2025-11-20
2. 工具設定位置變更：工具設定現在以 MCPToolset 物件的形式位於 tools 陣列中，而不是在 MCP 伺服器定義中
3. 更彈性的設定：新模式支援允許清單、拒絕清單和個別工具設定



遷移步驟

之前（已棄用）：

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



常見遷移模式



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



已棄用的欄位說明