Claude Platform Docs
MessagesMCP 通道

疑難排解 MCP 通道

診斷通道堆疊中的連線、TLS、IP 驗證與 OAuth 路由問題。

經由通道的請求可能在三個層級之一失敗；請依序診斷：連往 tunnel edge（通道邊緣） 的對外連線、從 Anthropic 到您的 proxy（代理） 的 inner TLS（內層 TLS），然後是通往 upstream MCP server（上游 MCP 伺服器） 的路由與 IP 驗證。

快速參考

症狀原因修正方式
通道未出現在代理程式的 + MCP Server 選擇器中選擇器只會列出工作階段所屬工作區中、至少擁有一個有效憑證的通道。註冊 CA 憑證，或在建立該通道的工作區中開啟工作階段。
呼叫端看到 HTTP 500；cloudflared 記錄 No ingress rules were definedcloudflared 沒有本機目標。在 cloudflared 服務中加入 --url http://localhost:8080 與 network_mode: "service:mcp-proxy"。
代理記錄 no route for hosttunnel_domain 與指派的網域不符，或編輯了 config.yaml 卻未重新啟動。將 tunnel_domain 設為通道詳細資訊頁面上顯示的確切網域，然後重新啟動代理（docker compose restart mcp-proxy）。
代理記錄 IP validation failed: <ip> is not a private address上游 MCP 伺服器解析到 RFC1918 範圍之外。請參閱上游 IP 驗證。
代理以 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://<proxy>:8080 失敗並顯示 wrong version number屬預期行為；該監聽器是純文字 WebSocket。TLS 發生在 WS 串流內部。請改為透過 Managed Agent 或 Messages API 進行驗證。

以下各節涵蓋需要超過一行修正的失敗情況。

OAuth 在來源 IP 允許清單後方失敗

當您的授權伺服器的來源 IP 允許清單阻擋 Anthropic 後端存取 /token、/register 與探索端點時，OAuth 流程會失敗。如果您不想將 Anthropic 的出口範圍加入允許清單，可以將後端對後端的 OAuth 呼叫經由通道路由，同時將面向瀏覽器的 /authorize 端點保留在您現有的公開主機名稱上。

  1. 為授權伺服器新增代理路由

    routes:
  mcp: http://your-mcp-server:8080
  auth: http://your-auth-server:8080

    編輯 routes 後請重新啟動代理（docker compose restart mcp-proxy，或 helm upgrade）。

  2. 提供分離端點的探索中繼資料

    您的授權伺服器的 /.well-known/oauth-authorization-server 回應應將 authorization_endpoint 指向您現有已加入允許清單的主機名稱，其餘全部指向通道：

    {
  "issuer": "https://auth.<tunnel-domain>",
  "authorization_endpoint": "https://<your-allowlisted-host>/authorize",
  "token_endpoint": "https://auth.<tunnel-domain>/token",
  "registration_endpoint": "https://auth.<tunnel-domain>/register",
  "code_challenge_methods_supported": ["S256"]
}

  3. 將 MCP 伺服器指向通道簽發者

    您的 MCP 伺服器的 /.well-known/oauth-protected-resource 回應應將通道主機名稱作為其授權伺服器來參照：

    {
  "resource": "https://mcp.<tunnel-domain>",
  "authorization_servers": ["https://auth.<tunnel-domain>"]
}

採用此設定後，使用者的瀏覽器會存取您現有主機名稱上的 /authorize（您的允許清單已允許），而 Anthropic 的後端則經由通道存取 /token、/register 與探索文件。

設定元件驗證失敗

setup component（設定元件）（Helm Job 或 Compose 的 setup 服務）透過您的聯合規則交換 OIDC JWT，以向 Tunnels API 進行驗證。當交換失敗時，請參閱 Workload Identity Federation 參考文件中的疑難排解失敗的交換；失敗模式（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 資源，因此重試前請先將其刪除：

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 符合 *.<tunnel-domain>。
  • 簽署的 CA 已針對此通道向 Anthropic 註冊。

完整的驗證規則請參閱憑證需求。

上游 IP 驗證

為了防護 SSRF，代理預設只會連線至 RFC1918 私有範圍（10.0.0.0/8、172.16.0.0/12、192.168.0.0/16）內的位址。代理到上游的連線僅支援 IPv4。（網路需求中的 cloudflared 到邊緣出口範圍是另一個躍點。）

如果代理記錄 IP validation failed: <ip> 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 伺服器所使用的私有範圍：

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

Was this page helpful?