訊息MCP 通道

MCP 通道參考

代理伺服器設定欄位、Tunnels REST API、憑證需求，以及設定元件。

MCP 通道目前處於研究預覽階段。申請存取權限以進行試用。

代理伺服器設定

代理伺服器會從 /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 的映射。請參閱路由比對。	必填
`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 伺服器。

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

Tunnels API

請參閱 MCP 通道 Admin API 參考以取得所有端點、請求與回應結構描述，以及各語言的範例。

所有 MCP 通道端點都需要具有 org:manage_tunnels 範圍的 bearer token，該 token 需透過 Workload Identity Federation 取得。不接受 Admin API 金鑰。

每個請求都必須包含以下標頭：

標頭	值
`Authorization`	`Bearer <token>`（經 WIF 交換取得的 token）
`anthropic-version`	`2023-06-01`
`anthropic-beta`	`mcp-tunnels-2026-05-19`

憑證需求

設定元件會自動產生符合規範的憑證。以下需求僅適用於您透過自己的 PKI 簽發憑證的情況。

CA 憑證

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

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

伺服器憑證

由代理伺服器在內層 TLS 期間出示。

由已註冊的 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`

附加至您在 Console 中建立的通道、產生 CA 與伺服器憑證、註冊 CA、擷取通道 token，並將所有輸出寫入目的地。

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

此命令透過 Workload Identity Federation 進行驗證。它會讀取 ANTHROPIC_FEDERATION_RULE_ID、ANTHROPIC_ORGANIZATION_ID、ANTHROPIC_WORKSPACE_ID（選填），以及 ANTHROPIC_IDENTITY_TOKEN_FILE 或 ANTHROPIC_IDENTITY_TOKEN 其中之一。請參閱 WIF 參考以了解這些變數目前的語意；設定元件會從聯合規則推導出服務帳戶，因此不需要另外提供 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 天時成為無操作（no-op），因此可以安全地依固定排程執行。

Was this page helpful?

訊息MCP 通道

MCP 通道參考

代理伺服器設定欄位、Tunnels REST API、憑證需求，以及設定元件。

MCP 通道目前處於研究預覽階段。申請存取權限以進行試用。

代理伺服器設定

代理伺服器會從 /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 的映射。請參閱路由比對。	必填
`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 其中之一；否則代理伺服器將沒有上游憑證的信任錨點。

路由比對

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

Tunnels API

請參閱 MCP 通道 Admin API 參考以取得所有端點、請求與回應結構描述，以及各語言的範例。

所有 MCP 通道端點都需要具有 org:manage_tunnels 範圍的 bearer token，該 token 需透過 Workload Identity Federation 取得。不接受 Admin API 金鑰。

每個請求都必須包含以下標頭：

標頭	值
`Authorization`	`Bearer <token>`（經 WIF 交換取得的 token）
`anthropic-version`	`2023-06-01`
`anthropic-beta`	`mcp-tunnels-2026-05-19`

憑證需求

設定元件會自動產生符合規範的憑證。以下需求僅適用於您透過自己的 PKI 簽發憑證的情況。

CA 憑證

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

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

伺服器憑證

由代理伺服器在內層 TLS 期間出示。

由已註冊的 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 init`

附加至您在 Console 中建立的通道、產生 CA 與伺服器憑證、註冊 CA、擷取通道 token，並將所有輸出寫入目的地。

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

`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 天時成為無操作（no-op），因此可以安全地依固定排程執行。

Was this page helpful?