---
title: MCP 通道參考
url: https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-tunnels/reference
description: 代理設定欄位、Tunnels REST API、憑證要求，以及設定元件。
---

<Note>
  「MCP tunnels」（MCP 通道）目前處於研究預覽階段。[申請存取權限](https://claude.com/form/mcp-tunnels)即可試用。
</Note>

## 代理設定

[代理（proxy）](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-tunnels/concepts#components)會從 `/etc/mcp-gateway/config.yaml`（Compose）或已渲染的 ConfigMap（Helm，由 `gateway.config.*` 填入）讀取其設定。

| 欄位                                | 說明                                                                                                                               | 預設值                   |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `listen_addr`                     | 要監聽的位址與連接埠。                                                                                                                      | 必填                    |
| `log_level`                       | 日誌詳細程度：`debug`、`info`、`warn` 或 `error`。                                                                                          | `info`                |
| `shutdown_timeout`                | 在優雅關閉期間等待進行中請求的時間長度。                                                                                                             | `30s`                 |
| `tunnel_domain`                   | 指派給通道的基礎網域。設定後，路由查詢會從傳入的主機名稱中去除此後綴，因此 `routes` 的鍵可以是裸子網域（`wiki`）。若為空，`routes` 的鍵必須是完全相符的完整主機名稱。                                  | 當 `routes` 的鍵為裸子網域時必填 |
| `tls.cert_file`                   | 伺服器 TLS 憑證的路徑。                                                                                                                   | 必填                    |
| `tls.key_file`                    | 伺服器 TLS 私鑰的路徑。                                                                                                                   | 必填                    |
| `routes`                          | 子網域或完整主機名稱對應至上游 URL 的映射。請參閱[路由比對](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-tunnels/reference#route-matching)。 | 必填                    |
| `upstream.allowed_ips`            | 代理被允許連線的 IPv4 CIDR 範圍或單一位址。與 `disable_ip_validation` 互斥。                                                                         | RFC1918 私有範圍          |
| `upstream.disable_ip_validation`  | 完全停用上游 IP 驗證。與 `allowed_ips` 互斥。                                                                                                 | `false`               |
| `upstream.tls.ca_file`            | 用於驗證上游 TLS 的 CA 套件。                                                                                                              | 無                     |
| `upstream.tls.include_system_cas` | 同時信任系統 CA 套件以用於上游 TLS。                                                                                                           | `false`               |

對於 `https://` 上游路由，請至少設定 `upstream.tls.ca_file` 或 `upstream.tls.include_system_cas` 其中之一；否則代理將沒有可用於上游憑證的信任錨點。

### 路由比對

`routes` 是一個扁平的字串映射（`map[string]string`），而非清單。代理會先以完全相符的方式查詢傳入的主機名稱，接著去除 `tunnel_domain` 後綴並比對剩餘的子網域。比對僅考慮主機名稱；請求路徑與查詢字串會原封不動地轉發至[上游 MCP 伺服器](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-tunnels/concepts#components)。

每個上游值必須嚴格為 `scheme://host:port` 格式。連接埠為必填。若包含路徑，將在載入設定時被拒絕，並顯示 `invalid upstream (must be scheme://host:port)`。

## Tunnels API

Tunnels REST API 位於 `/v1/tunnels`，支援建立、列出與封存通道、註冊 CA 憑證，以及揭示或輪替通道權杖。請參閱 [Tunnels API 參考](https://platform.claude.com/docs/zh-TW/api/beta/tunnels/list)以取得所有端點、請求與回應結構描述，以及範例。

<Note>
  先前位於 `/v1/organizations/tunnels` 的 Admin API 介面（beta 標頭 `mcp-tunnels-2026-05-19`，範圍 `org:manage_tunnels`）在遷移期間 仍可繼續使用，並仍記載於 [Admin API 參考](https://platform.claude.com/docs/zh-TW/api/beta/organization/mcp_tunnels)中，附有棄用 通知。若要遷移，請將路徑更新為 `/v1/tunnels`、將 beta 標頭更新為 `mcp-tunnels-2026-06-22`，並將您的 WIF 權杖範圍更新為 `workspace:manage_tunnels`。
</Note>

<Warning>
  所有 MCP 通道端點都需要透過 [Workload Identity Federation](https://platform.claude.com/docs/zh-TW/manage-claude/workload-identity-federation) 取得、具有 `workspace:manage_tunnels` 範圍的 bearer 權杖。不接受 Admin API 金鑰。
</Warning>

每個請求的必要標頭：

| 標頭                  | 值                             |
| ------------------- | ----------------------------- |
| `Authorization`     | `Bearer <token>`（經 WIF 交換的權杖） |
| `anthropic-version` | `2023-06-01`                  |
| `anthropic-beta`    | `mcp-tunnels-2026-06-22`      |

## 憑證要求

[設定元件（setup component）](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-tunnels/concepts#components)會自動產生符合規範的憑證。這些要求僅適用於您透過自己的 PKI 簽發憑證的情況。

### CA 憑證

使用 `POST /v1/tunnels/{tunnel_id}/certificates` 上傳。一個通道同時最多可持有兩個有效的 CA 憑證，以便進行零停機輪替。

* PEM 編碼、單一憑證，最大 8 kB。
* 具有 `BasicConstraints` 擴充欄位且為 `CA:TRUE`，並標記為 critical。
* 具有 `SubjectKeyIdentifier` 擴充欄位。
* `KeyUsage` 包含 `keyCertSign`。
* 在其有效期間內。
* RSA 2048 位元或以上，或 ECDSA P-256 或以上，並使用 SHA-256 或更強的簽章。

### 伺服器憑證

由代理在[內層 TLS](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-tunnels/concepts#components) 期間出示。

* 由已註冊的 CA 直接簽署（無中繼憑證）。
* 具有 `AuthorityKeyIdentifier` 擴充欄位，且與 CA 的 `SubjectKeyIdentifier` 相符。
* Subject Alternative Name 包含符合 `<route>.<tunnel-domain>` 的 DNS 名稱。萬用字元 `*.<tunnel-domain>` 可涵蓋所有路由。
* 若存在 `ExtendedKeyUsage` 擴充欄位，則其包含 `serverAuth`。
* 在其有效期間內。
* RSA 2048 位元或以上，或 ECDSA P-256 或以上，並使用 SHA-256 或更強的簽章。

設定元件會產生一個有效期五年的 ECDSA P-256 CA，以及一個具有萬用字元 SAN、有效期 90 天的 RSA 4096 位元伺服器憑證。

## 設定元件

設定元件以 `setup` 二進位檔的形式隨附於 `mcp-proxy` 映像檔中。請使用 `docker compose run --rm setup <subcommand>`（Compose）執行，或依賴 chart 的 hooks 與 CronJobs（Helm）。

### `setup init`

附加至現有通道（或在未提供通道 ID 時建立一個），接著產生 CA 與伺服器憑證、註冊 CA、擷取通道權杖，並將所有輸出寫入目的地。

| 旗標                | 說明                                                                           | 預設值                                                      |
| ----------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------- |
| `--api-url`       | Claude API 基礎 URL。亦可從 `API_URL` 讀取。                                          | 必填                                                       |
| `--tunnel-id`     | 要附加的通道 ID（`tnl_...`）。亦可從 `TUNNEL_ID` 讀取。省略時會建立新通道；重新執行時會重複使用已儲存於輸出中的通道 ID。   | 無（建立通道）                                                  |
| `--output`        | 輸出目的地：`dir:/path` 或 `k8s-secret:NAME`。Helm chart 會傳入 `k8s-secret:<release>`。 | `k8s-secret:mcp-tunnel`（在 Kubernetes pod 中執行時自動偵測；否則為必填） |
| `--cert-duration` | 伺服器憑證有效期間。                                                                   | `2160h`（90 天）                                            |
| `--token-version` | 變更偵測字串。新的值會在重新執行時觸發權杖輪替。Helm chart 與 Compose 範例皆傳入 `1` 作為初始值。                | 無                                                        |

此命令透過 [Workload Identity Federation](https://platform.claude.com/docs/zh-TW/manage-claude/workload-identity-federation) 進行驗證。它會讀取 `ANTHROPIC_FEDERATION_RULE_ID`、`ANTHROPIC_ORGANIZATION_ID`、`ANTHROPIC_WORKSPACE_ID`（選填），以及 `ANTHROPIC_IDENTITY_TOKEN_FILE` 或 `ANTHROPIC_IDENTITY_TOKEN` 其中恰好一個。請參閱 [WIF 參考](https://platform.claude.com/docs/zh-TW/manage-claude/wif-reference)以了解這些變數目前的語意；設定元件會從聯合規則推導出服務帳戶，因此不需要另外提供 `ANTHROPIC_SERVICE_ACCOUNT_ID`。

### `setup renew-cert`

簽發一張由已儲存的 CA 簽署的新伺服器憑證。不會進行任何 API 呼叫。

| 旗標                | 說明                                                                           | 預設值                                                      |
| ----------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------- |
| `--output`        | 輸出目的地：`dir:/path` 或 `k8s-secret:NAME`。Helm chart 會傳入 `k8s-secret:<release>`。 | `k8s-secret:mcp-tunnel`（在 Kubernetes pod 中執行時自動偵測；否則為必填） |
| `--cert-duration` | 新憑證的有效期間。                                                                    | `2160h`（90 天）                                            |
| `--renew-before`  | 若現有憑證的剩餘有效期超過此時間長度，則略過更新。                                                    | `0`（一律更新）                                                |

設定 `--renew-before=720h` 會使此命令在剩餘有效期超過 30 天時不執行任何動作，因此可安全地依固定排程執行。