--- title: 疑難排解 MCP 通道 url: https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-tunnels/troubleshooting description: 診斷通道堆疊中的連線、TLS、IP 驗證與 OAuth 路由問題。 --- 「MCP tunnels」（MCP 通道）目前處於研究預覽階段。[申請存取權限](https://claude.com/form/mcp-tunnels)即可試用。 經由通道的請求可能在三個層級之一失敗；請依序診斷：連往 [tunnel edge（通道邊緣）](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-tunnels/concepts#components) 的對外連線、從 Anthropic 到您的 [proxy（代理）](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-tunnels/concepts#components) 的 [inner TLS（內層 TLS）](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-tunnels/concepts#components)，然後是通往 [upstream MCP server（上游 MCP 伺服器）](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-tunnels/concepts#components) 的路由與 IP 驗證。 ## 快速參考 | 症狀 | 原因 | 修正方式 | | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | 通道未出現在代理程式的 **+ MCP Server** 選擇器中 | 選擇器只會列出工作階段所屬工作區中、至少擁有一個有效憑證的通道。 | 註冊 CA 憑證，或在建立該通道的工作區中開啟工作階段。 | | 呼叫端看到 HTTP 500；[cloudflared](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-tunnels/concepts#components) 記錄 `No ingress rules were defined` | cloudflared 沒有本機目標。 | 在 cloudflared 服務中加入 `--url http://localhost:8080` 與 `network_mode: "service:mcp-proxy"`。 | | 代理記錄 `no route for host` | `tunnel_domain` 與指派的網域不符，或編輯了 `config.yaml` 卻未重新啟動。 | 將 `tunnel_domain` 設為通道詳細資訊頁面上顯示的確切網域，然後重新啟動代理（`docker compose restart mcp-proxy`）。 | | 代理記錄 `IP validation failed: is not a private address` | 上游 MCP 伺服器解析到 RFC1918 範圍之外。 | 請參閱[上游 IP 驗證](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-tunnels/troubleshooting#upstream-ip-validation)。 | | 代理以 `cannot unmarshal !!seq into map[string]string` 結束 | `routes` 是 YAML 清單。 | 使用 `routes: { name: http://host:port }`。 | | 代理以 `open /data/tls.key: permission denied` 結束 | 金鑰權限為 `0600`；代理容器以非 root 身分執行。 | `chmod 644 data/tls.key`。 | | `curl https://:8080` 失敗並顯示 `wrong version number` | 屬預期行為；該監聽器是純文字 WebSocket。TLS 發生在 WS 串流內部。 | 請改為透過 [Managed Agent 或 Messages API](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers) 進行驗證。 | 以下各節涵蓋需要超過一行修正的失敗情況。 ## OAuth 在來源 IP 允許清單後方失敗 當您的授權伺服器的來源 IP 允許清單阻擋 Anthropic 後端存取 `/token`、`/register` 與探索端點時，OAuth 流程會失敗。如果您不想將 Anthropic 的出口範圍加入允許清單，可以將後端對後端的 OAuth 呼叫經由通道路由，同時將面向瀏覽器的 `/authorize` 端點保留在您現有的公開主機名稱上。 ```yaml routes: mcp: http://your-mcp-server:8080 auth: http://your-auth-server:8080 ``` 編輯 `routes` 後請重新啟動代理（`docker compose restart mcp-proxy`，或 `helm upgrade`）。 您的授權伺服器的 `/.well-known/oauth-authorization-server` 回應應將 `authorization_endpoint` 指向您現有已加入允許清單的主機名稱，其餘全部指向通道： ```json { "issuer": "https://auth.", "authorization_endpoint": "https:///authorize", "token_endpoint": "https://auth./token", "registration_endpoint": "https://auth./register", "code_challenge_methods_supported": ["S256"] } ``` 您的 MCP 伺服器的 `/.well-known/oauth-protected-resource` 回應應將通道主機名稱作為其授權伺服器來參照： ```json { "resource": "https://mcp.", "authorization_servers": ["https://auth."] } ``` 採用此設定後，使用者的瀏覽器會存取您現有主機名稱上的 `/authorize`（您的允許清單已允許），而 Anthropic 的後端則經由通道存取 `/token`、`/register` 與探索文件。 ## 設定元件驗證失敗 [setup component（設定元件）](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-tunnels/concepts#components)（Helm Job 或 Compose 的 `setup` 服務）透過您的聯合規則交換 OIDC JWT，以向 Tunnels API 進行驗證。當交換失敗時，請參閱 Workload Identity Federation 參考文件中的[疑難排解失敗的交換](https://platform.claude.com/docs/zh-TW/manage-claude/wif-reference#troubleshoot-a-failed-exchange)；失敗模式（subject、audience、issuer、JWKS、lifetime）相同。 通道特有的原因： * Chart 的預設 audience 為 `api.anthropic.com`（不含 scheme）。如果您規則的 audience 是 `https://api.anthropic.com`，請將 `api.wif.audience` 設為相符的值。 * 交換成功後 Tunnels API 回傳 `403`，表示規則的範圍未包含 `workspace:manage_tunnels`，或規則的服務帳戶不是該通道工作區的成員。請設定範圍並將服務帳戶加入工作區。 在 Helm 上，設定元件以 pre-install hook Job 的形式執行。失敗時，該 Job 會被保留以供檢查（`kubectl logs job/mcp-tunnel-setup -n mcp-tunnel`）。Helm 不會管理 hook 資源，因此重試前請先將其刪除： ```bash helm uninstall mcp-tunnel -n mcp-tunnel kubectl -n mcp-tunnel delete job mcp-tunnel-setup ``` ## 通道無法連線 請先檢查 cloudflared 日誌。常見原因： * `TUNNEL_TOKEN` 遺失、過期或複製錯誤。 * 防火牆阻擋了連往通道邊緣、連接埠 7844 的對外 TCP/UDP。 cloudflared 也可能記錄關於 UDP 接收緩衝區大小的警告；這是 QUIC 調校提示，而非錯誤。 ## 憑證錯誤 當 Anthropic 在內層 TLS 期間拒絕代理的憑證時，代理會記錄 `tls handshake failed`。請確認： * 伺服器憑證尚未過期。 * 憑證的 Subject Alternative Name 符合 `*.`。 * 簽署的 CA 已針對此通道向 Anthropic 註冊。 完整的驗證規則請參閱[憑證需求](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-tunnels/reference#certificate-requirements)。 ## 上游 IP 驗證 為了防護 SSRF，代理預設只會連線至 RFC1918 私有範圍（`10.0.0.0/8`、`172.16.0.0/12`、`192.168.0.0/16`）內的位址。代理到上游的連線僅支援 IPv4。（[網路需求](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-tunnels/overview#network-requirements)中的 cloudflared 到邊緣出口範圍是另一個躍點。） 如果代理記錄 `IP validation failed: is not a private address`，表示上游主機名稱解析到該範圍之外。在 Kubernetes 上，部分託管發行版會將 Service CIDR 配置在 RFC1918 之外；如果 `kubectl get svc kubernetes -n default -o jsonpath='{.spec.clusterIP}'` 回傳的位址在私有範圍之外，請查詢您叢集的 Service CIDR 並將其加入。 如果該位址是合法的，請將涵蓋範圍最窄的 CIDR 加入 `upstream.allowed_ips`。設定 `allowed_ips` 會**取代** RFC1918 預設值而非擴充它，因此請一併納入您其他上游 MCP 伺服器所使用的私有範圍： ```yaml config/mcp-proxy.yaml upstream: allowed_ips: - 10.0.0.0/8 - 172.16.0.0/12 - 192.168.0.0/16 - 127.0.0.0/8 # loopback, for local testing only ``` 除本機測試外，請避免使用 `0.0.0.0/0`；它會完全停用 SSRF 防護。