MCP 通道參考
代理設定欄位、Tunnels REST API、憑證要求，以及設定元件。
代理設定
代理（proxy）會從 /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
Tunnels REST API 位於 /v1/tunnels，支援建立、列出與封存通道、註冊 CA 憑證，以及揭示或輪替通道權杖。請參閱 Tunnels API 參考以取得所有端點、請求與回應結構描述，以及範例。
每個請求的必要標頭：
| 標頭 | 值 |
|---|---|
Authorization | Bearer <token>（經 WIF 交換的權杖） |
anthropic-version | 2023-06-01 |
anthropic-beta | mcp-tunnels-2026-06-22 |
憑證要求
設定元件（setup component）會自動產生符合規範的憑證。這些要求僅適用於您透過自己的 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 期間出示。
- 由已註冊的 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 進行驗證。它會讀取 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 天時不執行任何動作，因此可安全地依固定排程執行。
Was this page helpful?