API 中的 MCP

MCP 連接器

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

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

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

主要功能

直接 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 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 輔助工具（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();

// Connect to an MCP server
const transport = new StdioClientTransport({ command: 'mcp-server', args: [] });
const mcpClient = new Client({ name: 'my-client', version: '1.0.0' });
await mcpClient.connect(transport);

// List tools and convert them for the Claude API
const { tools } = await mcpClient.listTools();
const runner = await anthropic.beta.messages.toolRunner({
  model: 'claude-sonnet-4-5',
  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-5',
  max_tokens: 1024,
  messages: mcpMessages(messages),
});

使用 MCP 資源

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

import { mcpResourceToContent, mcpResourceToFile } from '@anthropic-ai/sdk/helpers/beta/mcp';

// As a content block in a message
const resource = await mcpClient.readResource({ uri: 'file:///path/to/doc.txt' });
await anthropic.beta.messages.create({
  model: 'claude-sonnet-4-5',
  max_tokens: 1024,
  messages: [
    {
      role: 'user',
      content: [
        mcpResourceToContent(resource),
        { type: 'text', text: 'Summarize this document' },
      ],
    },
  ],
});

// As a file upload
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-client-2025-04-04 beta 標頭，請按照本指南遷移到新版本。

主要變更

新的 beta 標頭：從 mcp-client-2025-04-04 變更為 mcp-client-2025-11-20
工具配置已移動：工具配置現在位於 tools 陣列中作為 MCPToolset 物件，而非在 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`（所有工具已啟用）	MCPToolset 不含 `default_config` 或 `configs`
`tool_configuration.enabled: false`	MCPToolset 搭配 `default_config.enabled: false`
`tool_configuration.allowed_tools: [...]`	MCPToolset 搭配 `default_config.enabled: false` 並在 `configs` 中啟用特定工具

已棄用版本：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 連接器

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

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

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

主要功能

直接 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 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 輔助工具（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();

// Connect to an MCP server
const transport = new StdioClientTransport({ command: 'mcp-server', args: [] });
const mcpClient = new Client({ name: 'my-client', version: '1.0.0' });
await mcpClient.connect(transport);

// List tools and convert them for the Claude API
const { tools } = await mcpClient.listTools();
const runner = await anthropic.beta.messages.toolRunner({
  model: 'claude-sonnet-4-5',
  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-5',
  max_tokens: 1024,
  messages: mcpMessages(messages),
});

使用 MCP 資源

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

import { mcpResourceToContent, mcpResourceToFile } from '@anthropic-ai/sdk/helpers/beta/mcp';

// As a content block in a message
const resource = await mcpClient.readResource({ uri: 'file:///path/to/doc.txt' });
await anthropic.beta.messages.create({
  model: 'claude-sonnet-4-5',
  max_tokens: 1024,
  messages: [
    {
      role: 'user',
      content: [
        mcpResourceToContent(resource),
        { type: 'text', text: 'Summarize this document' },
      ],
    },
  ],
});

// As a file upload
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-client-2025-04-04 beta 標頭，請按照本指南遷移到新版本。

主要變更

新的 beta 標頭：從 mcp-client-2025-04-04 變更為 mcp-client-2025-11-20
工具配置已移動：工具配置現在位於 tools 陣列中作為 MCPToolset 物件，而非在 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`（所有工具已啟用）	MCPToolset 不含 `default_config` 或 `configs`
`tool_configuration.enabled: false`	MCPToolset 搭配 `default_config.enabled: false`
`tool_configuration.allowed_tools: [...]`	MCPToolset 搭配 `default_config.enabled: false` 並在 `configs` 中啟用特定工具

已棄用版本：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?