訊息MCP 通道

MCP 通道疑難排解

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

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

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

快速參考

症狀	原因	修正方式
通道未出現在代理程式的 + MCP Server 選擇器中	選擇器僅列出工作階段所屬工作區中至少有一個有效憑證的通道。	註冊一個 CA 憑證，或在建立該通道的工作區中開啟工作階段。
呼叫端看到 HTTP 500；cloudflared 記錄 `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: <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 進行驗證。

以下各節涵蓋需要超過單行修正的故障情況。

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

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

為授權伺服器新增代理路由
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 指向您現有的允許清單主機名稱，並將其他所有項目指向通道：

{
  "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"]
}

將 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，表示規則的 scope 不包含 org:manage_tunnels，或規則的服務帳戶不是通道所屬工作區的成員。請設定 scope 並將服務帳戶加入工作區。

在 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

除了本機測試之外，請避免使用 0.0.0.0/0；它會完全停用 SSRF 防護。

Was this page helpful?

訊息MCP 通道

MCP 通道疑難排解

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

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

快速參考

症狀	原因	修正方式
通道未出現在代理程式的 + MCP Server 選擇器中	選擇器僅列出工作階段所屬工作區中至少有一個有效憑證的通道。	註冊一個 CA 憑證，或在建立該通道的工作區中開啟工作階段。
呼叫端看到 HTTP 500；cloudflared 記錄 `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: <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 進行驗證。

以下各節涵蓋需要超過單行修正的故障情況。

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

為授權伺服器新增代理路由
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 指向您現有的允許清單主機名稱，並將其他所有項目指向通道：

{
  "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"]
}

將 MCP 伺服器指向通道簽發者
您的 MCP 伺服器的 /.well-known/oauth-protected-resource 回應應將通道主機名稱參照為其授權伺服器：
{ "resource": "https://mcp.<tunnel-domain>", "authorization_servers": ["https://auth.<tunnel-domain>"] }

設定元件驗證失敗

通道特定的原因：

Chart 的預設 audience 為 api.anthropic.com（無 scheme）。如果您的規則的 audience 是 https://api.anthropic.com，請設定 api.wif.audience 使其相符。
成功交換後從 Tunnels API 收到 403，表示規則的 scope 不包含 org:manage_tunnels，或規則的服務帳戶不是通道所屬工作區的成員。請設定 scope 並將服務帳戶加入工作區。

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 驗證

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 防護。

Was this page helpful?