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-sonnet-4-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"
      }
    ]
  }'

屬性	類型	必需	說明
`type`	字串	是	目前僅支援 "url"
`url`	字串	是	MCP 伺服器的 URL。必須以 https:// 開頭
`name`	字串	是	此 MCP 伺服器的唯一識別碼。必須由 `tools` 陣列中的恰好一個 MCPToolset 參考。
`authorization_token`	字串	否	如果 MCP 伺服器需要，則為 OAuth 授權令牌。請參閱 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`	字串	是	必須為 "mcp_toolset"
`mcp_server_name`	字串	是	必須與 `mcp_servers` 陣列中定義的伺服器名稱相符
`default_config`	物件	否	應用於此集合中所有工具的預設配置。`configs` 中的個別工具配置將覆蓋這些預設值。
`configs`	物件	否	每個工具的配置覆蓋。鍵是工具名稱，值是配置物件。
`cache_control`	物件	否	此工具集的快取中斷點配置

屬性	類型	預設	說明
`enabled`	布林值	`true`	此工具是否啟用
`defer_loading`	布林值	`false`	如果為 true，工具說明最初不會傳送給模型。與工具搜尋工具搭配使用。

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

{
  "model": "claude-sonnet-4-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
      }
    }
  ]
}

使用以下命令執行檢查器。您需要在機器上安裝 Node.js。
```
npx @modelcontextprotocol/inspector
```
在左側邊欄中，針對「傳輸類型」，選擇「SSE」或「Streamable HTTP」。
輸入 MCP 伺服器的 URL。
在右側區域中，在「需要配置驗證？」後按一下「開啟驗證設定」按鈕。
按一下「快速 OAuth 流程」並在 OAuth 畫面上授權。
按照檢查器的「OAuth 流程進度」部分中的步驟操作，並按一下「繼續」直到達到「驗證完成」。
複製 access_token 值。
將其貼到 MCP 伺服器配置中的 authorization_token 欄位。

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "authenticated-server",
      "authorization_token": "YOUR_ACCESS_TOKEN_HERE"
    }
  ]
}

{
  "model": "claude-sonnet-4-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-sonnet-4-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`（所有工具啟用）	MCPToolset，無 `default_config` 或 `configs`
`tool_configuration.enabled: false`	MCPToolset，具有 `default_config.enabled: false`
`tool_configuration.allowed_tools: [...]`	MCPToolset，具有 `default_config.enabled: false` 和在 `configs` 中啟用的特定工具

{
  "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`	物件	已棄用：改用 `tools` 陣列中的 MCPToolset
`tool_configuration.enabled`	布林值	已棄用：在 MCPToolset 中使用 `default_config.enabled`
`tool_configuration.allowed_tools`	陣列	已棄用：在 MCPToolset 中使用允許清單模式搭配 `configs`

MCP 連接器

主要功能

限制

MCP 連接器

主要功能

限制

在 Messages API 中使用 MCP 連接器

基本範例

MCP 伺服器配置

欄位說明

MCP 工具集配置

基本結構

欄位說明

工具配置選項

配置合併

常見配置模式

使用預設配置啟用所有工具

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

拒絕清單 - 停用特定工具

混合 - 允許清單搭配每個工具的配置

驗證規則

回應內容類型

MCP 工具使用區塊

MCP 工具結果區塊

多個 MCP 伺服器

驗證

取得用於測試的存取令牌

使用存取令牌

遷移指南

主要變更

遷移步驟

常見遷移模式

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

棄用欄位說明