---
title: MCP 連接器
url: https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-connector
description: 無需 MCP 用戶端，直接從 Messages API 連接至遠端 MCP 伺服器，並對個別工具進行允許清單、拒絕清單或設定。
featureMetadata:
  status: beta
  betaHeader: mcp-client-2025-11-20
  zdr: not-eligible
  supportedPlatforms:
    Claude API: beta
    Claude Platform on AWS: beta
    Microsoft Foundry: beta
---

Claude 的「Model Context Protocol」，即 MCP 連接器（connector）功能，讓您無需另外的 MCP 用戶端，即可直接從 Messages API 連接至遠端 MCP 伺服器。

<Note>
  此功能的先前版本（`mcp-client-2025-04-04`）已棄用。請參閱[已棄用版本：mcp-client-2025-04-04](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-connector#deprecated-version-mcp-client-2025-04-04)。
</Note>

## 主要功能

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

## Claude 何時使用 MCP 工具

一旦連接了 MCP 伺服器，當使用者的請求對應到某個工具所描述的能力時，Claude 便會呼叫其工具，無論是明確的（「在 Jira 中搜尋未解決的錯誤」）或隱含的（在附加了 Jira 伺服器的情況下詢問「是什麼阻礙了發布？」）。

Claude **不會**針對有關已連接服務的一般知識問題呼叫 MCP 工具。在附加了 Notion 伺服器的情況下詢問「Notion 資料庫如何運作？」會直接回答；詢問「我的 Projects 資料庫裡有什麼？」則會觸發該工具。

您可以透過系統提示來引導 Claude 呼叫 MCP 工具的積極程度。請參閱 [Claude 何時使用工具](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/overview#when-claude-uses-tools)以取得一般指引與範例措辭。

## 限制

* 在 [MCP 規範](https://modelcontextprotocol.io/introduction#explore-mcp)的功能集中，目前僅支援[工具呼叫](https://modelcontextprotocol.io/docs/concepts/tools)。
* 伺服器必須透過 HTTP 公開（支援 Streamable HTTP 與 SSE 兩種傳輸方式）。本機 STDIO 伺服器無法直接連接。

## 在 Messages API 中使用 MCP 連接器

MCP 連接器使用兩個元件：

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

### 基本範例

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

<CodeGroup>
  ```bash cURL
  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-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"
        }
      ]
    }'
  ```

  ```bash CLI
  ant beta:messages create --beta mcp-client-2025-11-20 <<'YAML'
  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
  YAML
  ```

  ```python Python
  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)
  ```

  ```typescript TypeScript
  const anthropic = new Anthropic();

  const response = await anthropic.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"]
  });

  console.log(response);
  ```

  ```csharp C#
  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 1000,
      Messages = new List<BetaMessageParam>
      {
          new() { Role = Role.User, Content = "What tools do you have available?" }
      },
      McpServers = new List<BetaRequestMcpServerUrlDefinition>
      {
          new()
          {
              Url = "https://example-server.modelcontextprotocol.io/sse",
              Name = "example-mcp",
              AuthorizationToken = "YOUR_TOKEN"
          }
      },
      Tools = new List<BetaToolUnion>
      {
          new BetaMcpToolset("example-mcp")
      },
      Betas = [AnthropicBeta.McpClient2025_11_20]
  };

  var message = await client.Beta.Messages.Create(parameters);
  Console.WriteLine(message);
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 1000,
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What tools do you have available?")),
  	},
  	MCPServers: []anthropic.BetaRequestMCPServerURLDefinitionParam{
  		{
  			URL:                "https://example-server.modelcontextprotocol.io/sse",
  			Name:               "example-mcp",
  			AuthorizationToken: anthropic.String("YOUR_TOKEN"),
  		},
  	},
  	Tools: []anthropic.BetaToolUnionParam{
  		{OfMCPToolset: &anthropic.BetaMCPToolsetParam{
  			MCPServerName: "example-mcp",
  		}},
  	},
  	Betas: []anthropic.AnthropicBeta{
  		anthropic.AnthropicBetaMCPClient2025_11_20,
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response)
  ```

  ```java Java
  import com.anthropic.models.beta.messages.BetaMcpToolset;
  // ...
  import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;
  // ...

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1000L)
          .addUserMessage("What tools do you have available?")
          .addMcpServer(BetaRequestMcpServerUrlDefinition.builder()
              .url("https://example-server.modelcontextprotocol.io/sse")
              .name("example-mcp")
              .authorizationToken("YOUR_TOKEN")
              .build())
          .addTool(BetaMcpToolset.builder()
              .mcpServerName("example-mcp")
              .build())
          .addBeta(AnthropicBeta.MCP_CLIENT_2025_11_20)
          .build();

      BetaMessage response = client.beta().messages().create(params);
      IO.println(response);
  }
  ```

  ```php PHP
  $client = new Client();

  $message = $client->beta->messages->create(
      maxTokens: 1000,
      messages: [
          ['role' => 'user', 'content' => 'What tools do you have available?']
      ],
      model: 'claude-opus-5-5',
      mcpServers: [
          [
              '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'],
  );

  echo $message;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  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"]
  )

  puts response
  ```
</CodeGroup>

## MCP 伺服器設定

`mcp_servers` 陣列中的每個 MCP 伺服器定義了連線詳細資訊：

```json
{
  "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 授權權杖。請參閱[驗證](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-connector#authentication)以了解如何取得，或參閱 [MCP 規範](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)以了解協定詳細資訊。 |

## MCP 工具集設定

MCPToolset 位於 `tools` 陣列中，用於設定要啟用 MCP 伺服器的哪些工具以及應如何設定它們。

### 基本結構

```json
{
  "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 | 否  | 此工具集的[提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching)快取斷點設定。 |

使用 `mcp-client-2026-09-15` beta 標頭時，MCPToolset 也接受 `tools`，即伺服器工具清單的固定副本。請參閱[固定 MCP 伺服器的工具清單](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-connector#pin-mcp-tool-list)。

### 工具設定選項

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

| 屬性              | 類型      | 預設值     | 說明                                                                                                                       |
| --------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `enabled`       | boolean | `true`  | 此工具是否啟用。                                                                                                                 |
| `defer_loading` | boolean | `false` | 若為 true，工具描述一開始不會傳送給模型。與[工具搜尋工具](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/tool-search-tool)搭配使用。 |

如需 Anthropic 提供之工具的完整目錄以及 `defer_loading` 等選用屬性，請參閱[工具參考](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/tool-reference)。若要在大型工具集中進行搜尋，請參閱[工具搜尋工具](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/tool-search-tool)。

### 設定合併

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

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

範例：

```json
{
  "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）

## 常見設定模式

### 以預設設定啟用所有工具

最簡單的模式：啟用伺服器的所有工具：

```json
{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp"
}
```

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

將 `enabled: false` 設為預設值，然後明確啟用特定工具：

```json
{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false
  },
  "configs": {
    "search_events": {
      "enabled": true
    },
    "create_event": {
      "enabled": true
    }
  }
}
```

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

預設啟用所有工具，然後明確停用不需要的工具。在建構唯讀助理時，或當您希望在狀態變更前有人工確認步驟時，建議將寫入或破壞性工具加入拒絕清單：

```json
{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "configs": {
    "delete_all_events": {
      "enabled": false
    },
    "share_calendar_publicly": {
      "enabled": false
    }
  }
}
```

### 混合：允許清單搭配逐工具設定

將允許清單與每個工具的自訂設定結合：

```json
{
  "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 工具使用區塊

```json
{
  "type": "mcp_tool_use",
  "id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "name": "echo",
  "server_name": "example-mcp",
  "input": { "param1": "value1", "param2": "value2" }
}
```

### MCP 工具結果區塊

```json
{
  "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` 區塊開頭，每個被請求的伺服器各有一個區塊：

```json
{
  "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`：

```json
{
  "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 不會向伺服器請求：

<CodeGroup>
  ```bash cURL
  BODY='{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "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"
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What tools do you have available?"
      }
    ]
  }'

  # 第一個請求：toolset 尚未固定，因此 API 會向伺服器查詢
  # 其工具，而回應會以 mcp_tool_listing 區塊開頭。
  # tee 會將回應顯示在 stderr 上，同時由變數擷取回應內容。
  FIRST=$(curl -sS 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-2026-09-15" \
    -d "$BODY" | tee /dev/stderr)

  # 固定清單：將該區塊的 tools 複製到 toolset 中。API 會使用
  # 完全相同的這些項目，不會再次向伺服器查詢。
  TOOLS=$(jq '.content[] | select(.type == "mcp_tool_listing") | .tools' \
    <<<"$FIRST")
  PINNED=$(jq --argjson tools "$TOOLS" '.tools[0].tools = $tools' <<<"$BODY")

  # 使用已固定的 toolset 時，回應中不會有 mcp_tool_listing 區塊。
  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-2026-09-15" \
    -d "$PINNED"
  ```

  ```bash CLI
  request=$(cat <<'YAML'
  model: claude-opus-5-5
  max_tokens: 1024
  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
  messages:
    - role: user
      content: What tools do you have available?
  YAML
  )

  # 第一個請求：由於 toolset 未固定，API 會向伺服器查詢
  # 其工具，因此回應會以 mcp_tool_listing 區塊開頭。
  # tee 會將回應顯示在 stderr 上，同時由變數擷取回應內容。
  first=$(ant beta:messages create --beta mcp-client-2026-09-15 --format json \
    <<<"$request" | tee /dev/stderr)
  tools=$(jq -c '.content[] | select(.type == "mcp_tool_listing") | .tools' \
    <<<"$first")

  # 固定清單：將該區塊的 tools 複製到 toolset 中。--tool 旗標
  # 會取代請求主體中的 tools 陣列。API 會完全使用這些項目，
  # 不會再次查詢伺服器，因此回應中不會有 mcp_tool_listing 區塊。
  ant beta:messages create --beta mcp-client-2026-09-15 \
    --tool "{type: mcp_toolset, mcp_server_name: example-mcp, tools: $tools}" \
    <<<"$request"
  ```

  ```python Python
  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])
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const mcpServers: Anthropic.Beta.BetaRequestMCPServerURLDefinition[] = [
    {
      type: "url",
      url: "https://example-server.modelcontextprotocol.io/sse",
      name: "example-mcp",
      authorization_token: "YOUR_TOKEN"
    }
  ];
  const messages: Anthropic.Beta.BetaMessageParam[] = [
    { role: "user", content: "What tools do you have available?" }
  ];

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

  const listing = first.content.find((block) => block.type === "mcp_tool_listing");
  if (!listing) {
    throw new Error("The response has no mcp_tool_listing block.");
  }
  console.log(listing.tools.map((tool) => tool.name));

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

  // 使用已固定的 toolset 時，回應中不會有 mcp_tool_listing 區塊。
  console.log(second.content.map((block) => block.type));
  ```

  ```csharp C#
  using Anthropic.Models.Beta;
  using Anthropic.Models.Beta.Messages;
  using Messages = Anthropic.Models.Messages;

  AnthropicClient client = new();

  List<BetaRequestMcpServerUrlDefinition> mcpServers =
  [
      new()
      {
          Url = "https://example-server.modelcontextprotocol.io/sse",
          Name = "example-mcp",
          AuthorizationToken = "YOUR_TOKEN",
      },
  ];
  List<BetaMessageParam> messages =
  [
      new() { Role = Role.User, Content = "What tools do you have available?" },
  ];

  // 第一個請求：toolset 尚未固定，因此 API 會向伺服器查詢
  // 其工具，而回應會以 mcp_tool_listing 區塊開頭。
  var first = await client.Beta.Messages.Create(new MessageCreateParams
  {
      Model = Messages::Model.ClaudeOpus5_5,
      MaxTokens = 1024,
      Betas = [AnthropicBeta.McpClient2026_09_15],
      McpServers = mcpServers,
      Tools = [new BetaMcpToolset("example-mcp")],
      Messages = messages,
  });

  var listing = first.Content
      .Select(block => block.Value)
      .OfType<BetaMcpToolListingBlock>()
      .First();
  Console.WriteLine(string.Join(", ", listing.Tools.Select(tool => tool.Name)));

  // 固定清單：將該區塊的 tools 複製到 toolset 中。API 會使用
  // 完全相同的這些項目，且不會再次查詢伺服器。
  var second = await client.Beta.Messages.Create(new MessageCreateParams
  {
      Model = Messages::Model.ClaudeOpus5_5,
      MaxTokens = 1024,
      Betas = [AnthropicBeta.McpClient2026_09_15],
      McpServers = mcpServers,
      Tools =
      [
          new BetaMcpToolset("example-mcp")
          {
              Tools =
              [
                  .. listing.Tools.Select(tool => new BetaMcpToolParam
                  {
                      Name = tool.Name,
                      Description = tool.Description,
                      InputSchema = tool.InputSchema,
                  }),
              ],
          },
      ],
      Messages = messages,
  });

  // 使用已固定的 toolset 時，回應中不會有 mcp_tool_listing 區塊。
  Console.WriteLine(string.Join(", ", second.Content.Select(block => block.Type)));
  ```

  ```go Go
  client := anthropic.NewClient()

  mcpServers := []anthropic.BetaRequestMCPServerURLDefinitionParam{
  	{
  		URL:                "https://example-server.modelcontextprotocol.io/sse",
  		Name:               "example-mcp",
  		AuthorizationToken: anthropic.String("YOUR_TOKEN"),
  	},
  }
  messages := []anthropic.BetaMessageParam{
  	anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What tools do you have available?")),
  }

  // 第一次請求：toolset 尚未固定，因此 API 會向伺服器查詢
  // 其工具，而回應會以 mcp_tool_listing 區塊開頭。
  first, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
  	Model:      anthropic.ModelClaudeOpus5_5,
  	MaxTokens:  1024,
  	Betas:      []anthropic.AnthropicBeta{anthropic.AnthropicBetaMCPClient2026_09_15},
  	MCPServers: mcpServers,
  	Tools: []anthropic.BetaToolUnionParam{
  		{OfMCPToolset: &anthropic.BetaMCPToolsetParam{MCPServerName: "example-mcp"}},
  	},
  	Messages: messages,
  })
  if err != nil {
  	log.Fatal(err)
  }

  var listing anthropic.BetaMCPToolListingBlock
  for _, block := range first.Content {
  	if listingBlock, ok := block.AsAny().(anthropic.BetaMCPToolListingBlock); ok {
  		listing = listingBlock
  		break
  	}
  }

  // 固定清單：將該區塊的 tools 複製到 toolset 中。API 會使用
  // 完全相同的這些項目，不會再次查詢伺服器。
  var toolNames []string
  var pinnedTools []anthropic.BetaMCPToolParam
  for _, tool := range listing.Tools {
  	toolNames = append(toolNames, tool.Name)
  	pinnedTools = append(pinnedTools, anthropic.BetaMCPToolParam{
  		Name:        tool.Name,
  		Description: anthropic.String(tool.Description),
  		InputSchema: tool.InputSchema,
  	})
  }
  fmt.Println(toolNames)

  second, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
  	Model:      anthropic.ModelClaudeOpus5_5,
  	MaxTokens:  1024,
  	Betas:      []anthropic.AnthropicBeta{anthropic.AnthropicBetaMCPClient2026_09_15},
  	MCPServers: mcpServers,
  	Tools: []anthropic.BetaToolUnionParam{
  		{OfMCPToolset: &anthropic.BetaMCPToolsetParam{
  			MCPServerName: "example-mcp",
  			Tools:         pinnedTools,
  		}},
  	},
  	Messages: messages,
  })
  if err != nil {
  	log.Fatal(err)
  }

  // 使用已固定的 toolset 時，回應中不會有 mcp_tool_listing 區塊。
  var blockTypes []string
  for _, block := range second.Content {
  	blockTypes = append(blockTypes, block.Type)
  }
  fmt.Println(blockTypes)
  ```

  ```java Java
  import com.anthropic.models.beta.AnthropicBeta;
  import com.anthropic.models.beta.messages.BetaMcpTool;
  import com.anthropic.models.beta.messages.BetaMcpToolListingBlock;
  import com.anthropic.models.beta.messages.BetaMcpToolset;
  import com.anthropic.models.beta.messages.BetaMessage;
  import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;
  import com.anthropic.models.beta.messages.MessageCreateParams;
  // ...

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      BetaRequestMcpServerUrlDefinition mcpServer = BetaRequestMcpServerUrlDefinition.builder()
          .url("https://example-server.modelcontextprotocol.io/sse")
          .name("example-mcp")
          .authorizationToken("YOUR_TOKEN")
          .build();

      // 第一次請求：toolset 尚未固定，因此 API 會向伺服器查詢
      // 其工具，而回應會以 mcp_tool_listing 區塊開頭。
      BetaMessage first = client.beta().messages().create(MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024)
          .addBeta(AnthropicBeta.MCP_CLIENT_2026_09_15)
          .addMcpServer(mcpServer)
          .addTool(BetaMcpToolset.builder()
              .mcpServerName("example-mcp")
              .build())
          .addUserMessage("What tools do you have available?")
          .build());

      BetaMcpToolListingBlock listing = first.content().stream()
          .flatMap(block -> block.mcpToolListing().stream())
          .findFirst()
          .orElseThrow();
      IO.println(listing.tools().stream().map(BetaMcpTool::name).toList());

      // 固定清單：將該區塊的 tools 複製到 toolset 中。API 會使用
      // 完全相同的這些項目，不會再次查詢伺服器。
      BetaMessage second = client.beta().messages().create(MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024)
          .addBeta(AnthropicBeta.MCP_CLIENT_2026_09_15)
          .addMcpServer(mcpServer)
          .addTool(BetaMcpToolset.builder()
              .mcpServerName("example-mcp")
              .tools(listing.tools().stream().map(BetaMcpTool::toParam).toList())
              .build())
          .addUserMessage("What tools do you have available?")
          .build());

      // 使用已固定的 toolset 時，回應中不會有 mcp_tool_listing 區塊。
      IO.println(second.content().stream()
          .map(block -> block.type().asString())
          .toList());
  }
  ```

  ```php PHP
  use Anthropic\Beta\AnthropicBeta;
  use Anthropic\Beta\Messages\BetaMCPTool;
  use Anthropic\Beta\Messages\BetaMCPToolListingBlock;
  // ...

  $client = new Client();

  $mcpServers = [
      [
          'type' => 'url',
          'url' => 'https://example-server.modelcontextprotocol.io/sse',
          'name' => 'example-mcp',
          'authorization_token' => 'YOUR_TOKEN',
      ],
  ];
  $messages = [['role' => 'user', 'content' => 'What tools do you have available?']];

  // 第一次請求：由於 toolset 尚未固定，API 會向伺服器查詢
  // 其工具，且回應會以 mcp_tool_listing 區塊開頭。
  $first = $client->beta->messages->create(
      model: Model::CLAUDE_OPUS_5_5,
      maxTokens: 1024,
      betas: [AnthropicBeta::MCP_CLIENT_2026_09_15],
      mcpServers: $mcpServers,
      tools: [['type' => 'mcp_toolset', 'mcp_server_name' => 'example-mcp']],
      messages: $messages,
  );

  $listing = array_find($first->content, fn ($block) => $block instanceof BetaMCPToolListingBlock);
  echo json_encode(array_map(fn (BetaMCPTool $tool) => $tool->name, $listing->tools)), PHP_EOL;

  // 固定清單：將該區塊的工具複製到 toolset 中。API 會使用
  // 完全相同的這些項目，且不會再次查詢伺服器。
  $second = $client->beta->messages->create(
      model: Model::CLAUDE_OPUS_5_5,
      maxTokens: 1024,
      betas: [AnthropicBeta::MCP_CLIENT_2026_09_15],
      mcpServers: $mcpServers,
      tools: [
          [
              'type' => 'mcp_toolset',
              'mcp_server_name' => 'example-mcp',
              'tools' => array_map(
                  fn (BetaMCPTool $tool) => [
                      'name' => $tool->name,
                      'description' => $tool->description,
                      'input_schema' => $tool->inputSchema,
                  ],
                  $listing->tools,
              ),
          ],
      ],
      messages: $messages,
  );

  // 使用已固定的 toolset 時，回應中不會有 mcp_tool_listing 區塊。
  echo json_encode(array_map(fn ($block) => $block->type, $second->content)), PHP_EOL;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

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

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

  listing = first.content.find { it.is_a?(Anthropic::Beta::BetaMCPToolListingBlock) }
  puts listing.tools.map(&:name).inspect

  # 固定清單：將該區塊的 tools 複製到 toolset 中。API 會使用
  # 完全相同的這些項目，且不會再次查詢伺服器。
  second = client.beta.messages.create(
    model: Anthropic::Model::CLAUDE_OPUS_5_5,
    max_tokens: 1024,
    betas: [Anthropic::AnthropicBeta::MCP_CLIENT_2026_09_15],
    mcp_servers:,
    tools: [
      {
        type: "mcp_toolset",
        mcp_server_name: "example-mcp",
        tools: listing.tools.map(&:to_h)
      }
    ],
    messages:
  )

  # 使用已固定的 toolset 時，回應中不會有 mcp_tool_listing 區塊。
  puts second.content.map(&:type).inspect
  ```
</CodeGroup>

若同時使用 `inline-tools-2026-09-15` beta 標頭，您可以在對話進行中新增 MCP 伺服器。請參閱[在對話中途新增 MCP 伺服器](https://platform.claude.com/docs/zh-TW/build-with-claude/mid-conversation-system-messages#add-an-mcp-server-mid-conversation-beta)。

## 多個 MCP 伺服器

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

```json
{
  "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 會根據工具名稱與描述進行選擇。清楚、具體的工具描述可提升選擇準確度。對於大型工具集（跨多個伺服器的數十個工具），請考慮搭配[工具搜尋工具](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/tool-search-tool)啟用 [`defer_loading`](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-connector#tool-configuration-options)，以便每次查詢僅呈現相關的工具。

## 驗證

對於需要 OAuth 驗證的 MCP 伺服器，您需要取得存取權杖。MCP 連接器測試版支援在 MCP 伺服器定義中傳遞 `authorization_token` 參數。 API 使用者應在進行 API 呼叫之前處理 OAuth 流程並取得存取權杖，並視需要重新整理權杖。

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

MCP inspector 可引導您完成取得測試用存取權杖的流程。

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

   ```bash
   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 伺服器設定中使用它：

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

如需 OAuth 流程的詳細說明，請參閱 MCP 規範中的[授權章節](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)。

## 用戶端 MCP 輔助函式

如果您自行管理 MCP 用戶端連線（例如使用本機 stdio 伺服器、MCP 提示或 MCP 資源），SDK 提供了可在 MCP 類型與 Claude API 類型之間轉換的輔助函式。當您將適用於您語言的 MCP SDK（例如 [TypeScript MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)）與 Anthropic SDK 搭配使用時，這可省去手動轉換的程式碼。

<Note>
  當您有可透過 URL 存取的遠端伺服器且只需要工具支援時，請使用 [`mcp_servers` API 參數](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-connector#using-the-mcp-connector-in-the-messages-api)。當您需要本機伺服器、提示、資源，或需要透過基礎 SDK 對連線進行更多控制時，請使用用戶端輔助函式。
</Note>

### 安裝

同時安裝 Anthropic SDK 和 MCP SDK：

<Tabs>
  <Tab title="Python">
    MCP 輔助函式包含在 `mcp` extra 中，需要 Python 3.10 或更新版本：

    ```bash
    pip install "anthropic[mcp]"
    ```
  </Tab>

  <Tab title="TypeScript">
    ```bash
    npm install @anthropic-ai/sdk @modelcontextprotocol/sdk
    ```
  </Tab>

  <Tab title="C#">
    輔助函式位於獨立的 `Anthropic.Mcp` 套件中；MCP 用戶端本身則來自官方的 [ModelContextProtocol 套件](https://www.nuget.org/packages/ModelContextProtocol)：

    ```bash
    dotnet add package Anthropic.Mcp
    dotnet add package ModelContextProtocol
    ```
  </Tab>

  <Tab title="Go">
    輔助函式位於 Go SDK 的 `mcp` 子套件中，該子套件建構於 [MCP Go SDK](https://github.com/modelcontextprotocol/go-sdk) 之上：

    ```bash
    go get github.com/anthropics/anthropic-sdk-go/mcp
    ```
  </Tab>

  <Tab title="Java">
    輔助函式位於獨立的 `anthropic-java-mcp` artifact 中，需要 Java 17 或更新版本（基礎 SDK 支援 Java 8）。請將其與基礎的 `anthropic-java` 相依套件一起加入：

    <Tabs>
      <Tab title="Gradle">
        ```kotlin
        implementation("com.anthropic:anthropic-java:2.73.0")
        implementation("com.anthropic:anthropic-java-mcp:2.73.0")
        ```
      </Tab>

      <Tab title="Maven">
        ```xml
        <dependency>
            <groupId>com.anthropic</groupId>
            <artifactId>anthropic-java</artifactId>
            <version>2.73.0</version>
        </dependency>
        <dependency>
            <groupId>com.anthropic</groupId>
            <artifactId>anthropic-java-mcp</artifactId>
            <version>2.73.0</version>
        </dependency>
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="PHP">
    輔助函式使用官方的 [MCP PHP SDK](https://packagist.org/packages/mcp/sdk)：

    ```bash
    composer require "anthropic-ai/sdk" "guzzlehttp/guzzle:^7" "mcp/sdk"
    ```
  </Tab>

  <Tab title="Ruby">
    輔助函式使用官方的 [`mcp` gem](https://rubygems.org/gems/mcp)：

    ```bash
    bundle add anthropic mcp
    ```
  </Tab>
</Tabs>

### 可用的輔助函式

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

<CodeGroup exclude="shell">
  ```python Python
  from anthropic.lib.tools.mcp import (
      async_mcp_tool,
      mcp_message,
      mcp_resource_to_content,
      mcp_resource_to_file,
  )
  ```

  ```typescript TypeScript
  import {
    mcpTools,
    mcpMessages,
    mcpResourceToContent,
    mcpResourceToFile
  } from "@anthropic-ai/sdk/helpers/beta/mcp";
  ```

  ```csharp C#
  using Anthropic.Helpers.Beta;
  using Anthropic.Helpers.Beta.Mcp;
  ```

  ```go Go
  import (
  	"github.com/anthropics/anthropic-sdk-go/mcp"
  )
  ```

  ```java Java
  import com.anthropic.helpers.McpBetaTool;
  import com.anthropic.mcp.BetaMcp;
  ```

  ```php PHP
  use Anthropic\Lib\Tools\BetaMcp;
  ```

  ```ruby Ruby
  require "anthropic"

  # 這些輔助程式公開於 Anthropic::Mcp 模組
  ```
</CodeGroup>

| 輔助函式                                                                                                                                                                                                                                                                                                                       | 說明                                                                                                                                                                                                                                                                                                            |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `async_mcp_tool(tool, mcp_client)` (typescript: `mcpTools(tools, mcpClient)`; csharp: `BetaMcp.ListToolsAsync(mcpClient)`; go: `mcp.NewBetaTools(tools, session)`; java: `BetaMcp.mcpTools(tools, mcpClient)`; php: `BetaMcp::tools($tools, $mcp)`; ruby: `Anthropic::Mcp.tools(tools, mcp_client)`)                       | 將 MCP 工具轉換為 Claude API 工具，以搭配 `client.beta.messages.tool_runner()` (typescript: `client.beta.messages.toolRunner()`; java: `client.beta().messages().toolRunner()`; php: `$client->beta->messages->toolRunner()`; csharp: `client.Beta.Messages.ToolRunner()`; go: `client.Beta.Messages.NewToolRunner()`) 使用 |
| `mcp_message(message)` (typescript: `mcpMessages(messages)`; csharp: `BetaMcp.Messages(messages)`; go: `mcp.ToMessage(message)`; java: `BetaMcp.mcpMessages(messages)`; php: `BetaMcp::message($message)`; ruby: `Anthropic::Mcp.message(message)`)                                                                        | 將 MCP 提示訊息轉換為 Claude API 訊息格式                                                                                                                                                                                                                                                                                 |
| `mcp_resource_to_content(resource)` (typescript: `mcpResourceToContent(resource)`; csharp: `BetaMcp.ResourceToContent(resource)`; go: `mcp.ResourceToBlock(resource)`; java: `BetaMcp.mcpResourceContents(resource)`; php: `BetaMcp::resourceToContent($resource)`; ruby: `Anthropic::Mcp.resource_to_contents(resource)`) | 將 MCP 資源轉換為 Claude API 內容區塊                                                                                                                                                                                                                                                                                   |
| `mcp_resource_to_file(resource)` (typescript: `mcpResourceToFile(resource)`; csharp: `BetaMcp.ResourceToFile(resource)`; go: `mcp.ResourceToFile(resource)`; java: `BetaMcp.mcpResourceFiles(resource)`; php: `BetaMcp::resourceToFile($resource)`; ruby: `Anthropic::Mcp.resource_to_files(resource)`)                    | 將 MCP 資源轉換為可供上傳的檔案物件                                                                                                                                                                                                                                                                                          |

### 使用 MCP 工具

轉換 MCP 工具以搭配 SDK 的[工具執行器](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/tool-runner)使用，它會自動處理工具執行：

<CodeGroup exclude="shell">
  ```python Python
  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())
  ```

  ```typescript TypeScript
  import {
    mcpTools,
    type MCPCallToolResultLike,
    type MCPClientLike
  } 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();

  // 連線到 MCP 伺服器
  const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
  const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
  await mcpClient.connect(transport);

  // 列出工具並將其轉換為 Claude API 格式
  const { tools } = await mcpClient.listTools();

  // MCP SDK 的 callTool 回傳型別仍包含 mcpTools 不接受的舊版結果形狀；
  // 在此將其窄化。待 MCPClientLike 放寬後即可移除。
  const mcpClientForTools: MCPClientLike = {
    callTool: (params) => mcpClient.callTool(params) as Promise<MCPCallToolResultLike>
  };

  const finalMessage = await anthropic.beta.messages.toolRunner({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "What tools do you have available?" }],
    tools: mcpTools(tools, mcpClientForTools)
  });

  console.log(finalMessage);
  ```

  ```csharp C#
  using Anthropic.Helpers.Beta;
  using Anthropic.Helpers.Beta.Mcp;
  using Anthropic.Models.Beta.Messages;
  using ModelContextProtocol.Client;
  using Messages = Anthropic.Models.Messages;

  var anthropic = new AnthropicClient();

  // 連線至 MCP 伺服器
  await using var mcpClient = await McpClient.CreateAsync(
      new StdioClientTransport(new StdioClientTransportOptions { Command = "mcp-server" })
  );

  // 列出工具並將其轉換為 Claude API 格式
  var tools = await BetaMcp.ListToolsAsync(mcpClient);
  var runner = anthropic.Beta.Messages.ToolRunner(
      new MessageCreateParams
      {
          Model = Messages::Model.ClaudeOpus5_5,
          MaxTokens = 1024,
          Messages =
          [
              new BetaMessageParam
              {
                  Role = Role.User,
                  Content = "What tools do you have available?",
              },
          ],
      },
      tools
  );

  var finalMessage = await runner.RunUntilDoneAsync();
  Console.WriteLine(finalMessage);
  ```

  ```go Go
  import (
  // ...

  // ...
  	"github.com/anthropics/anthropic-sdk-go/mcp"
  	mcpsdk "github.com/modelcontextprotocol/go-sdk/mcp"
  )

  func main() {
  	client := anthropic.NewClient()
  	ctx := context.Background()

  	// 連線到 MCP 伺服器
  	mcpClient := mcpsdk.NewClient(&mcpsdk.Implementation{Name: "my-client", Version: "1.0.0"}, nil)
  	session, err := mcpClient.Connect(ctx, &mcpsdk.CommandTransport{Command: exec.Command("mcp-server")}, nil)
  	if err != nil {
  		log.Fatal(err)
  	}
  	defer session.Close()

  	// 列出工具並將其轉換為 Claude API 格式
  	toolsResult, err := session.ListTools(ctx, nil)
  	if err != nil {
  		log.Fatal(err)
  	}
  	betaTools, err := mcp.NewBetaTools(toolsResult.Tools, session)
  	if err != nil {
  		log.Fatal(err)
  	}

  	runner := client.Beta.Messages.NewToolRunner(betaTools, anthropic.BetaToolRunnerParams{
  		BetaMessageNewParams: anthropic.BetaMessageNewParams{
  			Model:     anthropic.ModelClaudeOpus5_5,
  			MaxTokens: 1024,
  			Messages: []anthropic.BetaMessageParam{
  				anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What tools do you have available?")),
  			},
  		},
  	})

  	finalMessage, err := runner.RunToCompletion(ctx)
  	if err != nil {
  		log.Fatal(err)
  	}
  	fmt.Println(finalMessage.RawJSON())
  }
  ```

  ```java Java
  import com.anthropic.helpers.BetaToolRunner;
  import com.anthropic.helpers.McpBetaTool;
  import com.anthropic.mcp.BetaMcp;
  import com.anthropic.models.beta.messages.BetaMessage;
  import com.anthropic.models.beta.messages.MessageCreateParams;
  import com.anthropic.models.messages.Model;
  import io.modelcontextprotocol.client.McpClient;
  import io.modelcontextprotocol.client.McpSyncClient;
  import io.modelcontextprotocol.client.transport.ServerParameters;
  import io.modelcontextprotocol.client.transport.StdioClientTransport;
  import io.modelcontextprotocol.json.McpJsonDefaults;
  import io.modelcontextprotocol.spec.McpSchema;
  // ...

  void main() throws Exception {
      AnthropicClient anthropic = AnthropicOkHttpClient.fromEnv();

      // 連線到 MCP 伺服器
      StdioClientTransport transport = new StdioClientTransport(
              ServerParameters.builder("mcp-server").build(), McpJsonDefaults.getMapper());

      try (McpSyncClient mcpClient = McpClient.sync(transport)
              .clientInfo(new McpSchema.Implementation("my-client", "1.0.0"))
              .build()) {

          mcpClient.initialize();

          // 列出工具並將其轉換為 Claude API 格式
          List<McpBetaTool> betaTools = BetaMcp.mcpTools(mcpClient.listTools().tools(), mcpClient);

          MessageCreateParams params = MessageCreateParams.builder()
                  .model(Model.CLAUDE_OPUS_5_5)
                  .maxTokens(1024L)
                  .addUserMessage("What tools do you have available?")
                  .addTools(betaTools)
                  .build();

          // 執行器在每個助理回合產生一則訊息；最後一則即為最終回應
          BetaToolRunner runner = anthropic.beta().messages().toolRunner(params);
          BetaMessage finalMessage = null;
          for (BetaMessage message : runner) {
              finalMessage = message;
          }
          IO.println(finalMessage);
      }
  }
  ```

  ```php PHP
  use Anthropic\Lib\Tools\BetaMcp;
  use Mcp\Client;
  use Mcp\Client\Transport\HttpTransport;

  $anthropic = new Anthropic();

  // 連線至 MCP 伺服器。PHP MCP 用戶端透過 HTTP 連線；請將此處
  // 指向您伺服器的端點。
  $mcp = Client::builder()->build();
  $mcp->connect(new HttpTransport('http://localhost:8000/mcp'));

  // 列出工具並將其轉換為 Claude API 可用的格式
  $runner = $anthropic->beta->messages->toolRunner(
      maxTokens: 1024,
      messages: [['role' => 'user', 'content' => 'What tools do you have available?']],
      model: 'claude-opus-5-5',
      tools: BetaMcp::tools($mcp->listTools()->tools, $mcp),
  );

  echo $runner->runUntilDone(), "\n";
  ```

  ```ruby Ruby
  require "mcp"

  anthropic = Anthropic::Client.new

  # 連線到 MCP 伺服器
  transport = MCP::Client::Stdio.new(command: "mcp-server")
  mcp_client = MCP::Client.new(transport: transport)
  mcp_client.connect

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

  final_message = runner.run_until_finished.last
  puts final_message
  ```
</CodeGroup>

### 使用 MCP 提示

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

<CodeGroup exclude="shell">
  ```python Python
  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)
  ```

  ```typescript TypeScript
  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-opus-5-5",
    max_tokens: 1024,
    messages: mcpMessages(messages)
  });

  console.log(response);
  ```

  ```csharp C#
  var prompt = await mcpClient.GetPromptAsync("my-prompt");
  var response = await anthropic.Beta.Messages.Create(
      new MessageCreateParams
      {
          Model = Messages::Model.ClaudeOpus5_5,
          MaxTokens = 1024,
          Messages = BetaMcp.Messages(prompt.Messages),
      }
  );

  Console.WriteLine(response);
  ```

  ```go Go
  prompt, err := session.GetPrompt(ctx, &mcpsdk.GetPromptParams{Name: "my-prompt"})
  if err != nil {
  	log.Fatal(err)
  }

  messages := make([]anthropic.BetaMessageParam, 0, len(prompt.Messages))
  for _, promptMessage := range prompt.Messages {
  	message, err := mcp.ToMessage(promptMessage)
  	if err != nil {
  		log.Fatal(err)
  	}
  	messages = append(messages, message)
  }

  response, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 1024,
  	Messages:  messages,
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response.RawJSON())
  ```

  ```java Java
  McpSchema.GetPromptResult prompt = mcpClient.getPrompt(
          new McpSchema.GetPromptRequest("my-prompt", Map.of()));

  BetaMessage response = anthropic.beta().messages().create(MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024L)
          .messages(BetaMcp.mcpMessages(prompt.messages()))
          .build());

  IO.println(response);
  ```

  ```php PHP
  $prompt = $mcp->getPrompt('my-prompt');

  $response = $anthropic->beta->messages->create(
      maxTokens: 1024,
      messages: array_map(BetaMcp::message(...), $prompt->messages),
      model: 'claude-opus-5-5',
  );

  echo $response, "\n";
  ```

  ```ruby Ruby
  prompt = mcp_client.get_prompt(name: "my-prompt")

  response = anthropic.beta.messages.create(
    model: "claude-opus-5-5",
    max_tokens: 1024,
    messages: prompt["messages"].map { |message| Anthropic::Mcp.message(message) }
  )

  puts response
  ```
</CodeGroup>

### 使用 MCP 資源

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

<CodeGroup exclude="shell">
  ```python Python
  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)
  ```

  ```typescript TypeScript
  import { mcpResourceToContent, mcpResourceToFile } from "@anthropic-ai/sdk/helpers/beta/mcp";

  // 作為訊息中的內容區塊
  const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
  const response = await anthropic.beta.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: [
          mcpResourceToContent(resource),
          { type: "text", text: "Summarize this document" }
        ]
      }
    ]
  });
  console.log(response);

  // 作為檔案上傳
  const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
  const uploaded = await anthropic.files.upload({ file: mcpResourceToFile(fileResource) });
  console.log(uploaded.id);
  ```

  ```csharp C#
  // 作為訊息中的內容區塊
  var resource = await mcpClient.ReadResourceAsync("file:///path/to/doc.txt");
  var response = await anthropic.Beta.Messages.Create(
      new MessageCreateParams
      {
          Model = Messages::Model.ClaudeOpus5_5,
          MaxTokens = 1024,
          Messages =
          [
              new BetaMessageParam
              {
                  Role = Role.User,
                  Content = new BetaMessageParamContent(
                      [
                          BetaMcp.ResourceToContent(resource),
                          new BetaTextBlockParam { Text = "Summarize this document" },
                      ]
                  ),
              },
          ],
      }
  );

  Console.WriteLine(response);

  // 作為檔案上傳
  var fileResource = await mcpClient.ReadResourceAsync("file:///path/to/data.json");
  var (filename, data, mediaType) = BetaMcp.ResourceToFile(fileResource);

  // 明確建構檔案部分，使資源的檔名與 MIME 類型
  // 能一併帶入上傳。
  var file = new BinaryContent { Stream = new MemoryStream(data), FileName = filename };
  if (mediaType is not null)
  {
      file.ContentType = new(mediaType);
  }

  var uploaded = await anthropic.Files.Upload(new FileUploadParams { File = file });
  Console.WriteLine(uploaded.ID);
  ```

  ```go Go
  // 作為訊息中的內容區塊
  resource, err := session.ReadResource(ctx, &mcpsdk.ReadResourceParams{URI: "file:///path/to/doc.txt"})
  if err != nil {
  	log.Fatal(err)
  }
  block, err := mcp.ResourceToBlock(resource)
  if err != nil {
  	log.Fatal(err)
  }

  response, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 1024,
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(
  			// ResourceToBlock 回傳 tool-result 內容聯集型別；訊息
  			// 內容是另一個獨立的聯集型別，因此需重新包裝共用的變體
  			// （mcp.ToMessage 在內部也做同樣的事）。
  			anthropic.BetaContentBlockParamUnion{
  				OfText:     block.OfText,
  				OfImage:    block.OfImage,
  				OfDocument: block.OfDocument,
  			},
  			anthropic.NewBetaTextBlock("Summarize this document"),
  		),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response.RawJSON())

  // 作為檔案上傳
  fileResult, err := session.ReadResource(ctx, &mcpsdk.ReadResourceParams{URI: "file:///path/to/data.json"})
  if err != nil {
  	log.Fatal(err)
  }
  fileReader, err := mcp.ResourceToFile(fileResult)
  if err != nil {
  	log.Fatal(err)
  }
  uploaded, err := client.Files.Upload(ctx, anthropic.FileUploadParams{File: fileReader})
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(uploaded.ID)
  ```

  ```java Java
  // 作為訊息中的內容區塊
  McpSchema.ReadResourceResult resource = mcpClient.readResource(
          new McpSchema.ReadResourceRequest("file:///path/to/doc.txt"));

  List<BetaContentBlockParam> content =
          new ArrayList<>(BetaMcp.mcpResourceContents(resource));
  content.add(BetaContentBlockParam.ofText(
          BetaTextBlockParam.builder().text("Summarize this document").build()));

  BetaMessage response = anthropic.beta().messages().create(MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024L)
          .addUserMessageOfBetaContentBlockParams(content)
          .build());

  IO.println(response);

  // 作為檔案上傳
  McpSchema.ReadResourceResult fileResource = mcpClient.readResource(
          new McpSchema.ReadResourceRequest("file:///path/to/data.json"));

  McpResourceFile resourceFile = BetaMcp.mcpResourceFiles(fileResource).getFirst();

  // 明確建構檔案部分，使資源的檔名與 MIME 類型
  // 能一併帶入上傳。
  MultipartField.Builder<InputStream> fileField = MultipartField.<InputStream>builder()
          .value(new ByteArrayInputStream(resourceFile.content()))
          .filename(resourceFile.filename());
  if (resourceFile.mimeType() != null) {
      fileField.contentType(resourceFile.mimeType());
  }

  var uploaded = anthropic.files().upload(FileUploadParams.builder()
          .file(fileField.build())
          .build());

  IO.println(uploaded.id());
  ```

  ```php PHP
  // 作為訊息中的內容區塊
  $resource = $mcp->readResource('file:///path/to/doc.txt');

  $response = $anthropic->beta->messages->create(
      maxTokens: 1024,
      messages: [
          [
              'role' => 'user',
              'content' => [
                  BetaMcp::resourceToContent($resource),
                  ['type' => 'text', 'text' => 'Summarize this document'],
              ],
          ],
      ],
      model: 'claude-opus-5-5',
  );

  echo $response, "\n";

  // 作為檔案上傳
  $fileResource = $mcp->readResource('file:///path/to/data.json');
  $file = $anthropic->files->upload(file: BetaMcp::resourceToFile($fileResource));
  echo $file->id, "\n";
  ```

  ```ruby Ruby
  # 作為訊息中的內容區塊
  resource = mcp_client.read_resource(uri: "file:///path/to/doc.txt")

  response = anthropic.beta.messages.create(
    model: "claude-opus-5-5",
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: [
          *Anthropic::Mcp.resource_to_contents(resource),
          { type: "text", text: "Summarize this document" }
        ]
      }
    ]
  )

  puts response

  # 作為檔案上傳
  file_resource = mcp_client.read_resource(uri: "file:///path/to/data.json")
  file = Anthropic::Mcp.resource_to_files(file_resource).first
  uploaded_file = anthropic.files.upload(file: file)
  puts uploaded_file.id
  ```
</CodeGroup>

### 錯誤處理

如果 Claude API 不支援某個 MCP 值，轉換函式會以 `UnsupportedMCPValueError` (go: `UnsupportedValueError`; java, csharp: `AnthropicInvalidDataException`) 失敗（以拋出例外的方式，或在 Go 中以傳回錯誤的方式）。這可能發生在不支援的內容類型、MIME 類型或資源連結上（請在轉換之前使用您的 MCP 用戶端解析資源連結）。

## 批次請求

您可以在 [Message Batches API](https://platform.claude.com/docs/zh-TW/build-with-claude/batch-processing) 請求中包含 `mcp_servers`。透過 Batches API 進行的 MCP 工具呼叫，其計價與一般 Messages API 請求中的相同。

## 資料保留

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

如需所有功能的 ZDR 資格，請參閱 [API 與資料保留](https://platform.claude.com/docs/zh-TW/manage-claude/api-and-data-retention)。

## 遷移指南

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

### 主要變更

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

### 遷移步驟

**之前（已棄用）：**

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

**之後（目前）：**

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

### 常見遷移模式

| 舊模式                                       | 新模式                                                                |
| ----------------------------------------- | ------------------------------------------------------------------ |
| 無 `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

<Warning>
  此版本已被棄用。請使用前述的[遷移指南](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-connector#migration-guide)遷移至 `mcp-client-2025-11-20`。
</Warning>

MCP 連接器的先前版本將工具設定直接包含在 MCP 伺服器定義中：

```json
{
  "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` 的允許清單模式       |