SPB Git

Repository Public

troubleshooting.md 10.1 KB 125 lines markdown

1---2title: Troubleshoot MCP tunnels3url: https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting4description: Diagnose connectivity, TLS, IP validation, and OAuth routing issues in a tunnel stack.5---67<Note>8  MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them.9</Note>1011A request through the tunnel can fail at one of three layers; diagnose them in order: the outbound connection to the [tunnel edge](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components), the [inner TLS](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) from Anthropic to your [proxy](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components), then routing and IP validation toward the [upstream MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components).1213## Quick reference1415| Symptom                                                                                                                                                        | Cause                                                                                               | Fix                                                                                                                                                                   |16| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |17| Tunnel doesn't appear in the agent **+ MCP Server** picker                                                                                                     | The picker only lists tunnels in the session's workspace that have at least one active certificate. | Register a CA certificate, or open the session in the workspace the tunnel was created in.                                                                            |18| Caller sees HTTP 500; [cloudflared](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) logs `No ingress rules were defined` | cloudflared has no local target.                                                                    | Add `--url http://localhost:8080` and `network_mode: "service:mcp-proxy"` to the cloudflared service.                                                                 |19| Proxy logs `no route for host`                                                                                                                                 | `tunnel_domain` doesn't match the assigned domain, or `config.yaml` was edited without restarting.  | Set `tunnel_domain` to the exact domain shown on the tunnel detail page, then restart the proxy (`docker compose restart mcp-proxy`).                                 |20| Proxy logs `IP validation failed: <ip> is not a private address`                                                                                               | Upstream MCP server resolves outside RFC1918.                                                       | See [Upstream IP validation](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting#upstream-ip-validation).                                |21| Proxy exits with `cannot unmarshal !!seq into map[string]string`                                                                                               | `routes` is a YAML list.                                                                            | Use `routes: { name: http://host:port }`.                                                                                                                             |22| Proxy exits with `open /data/tls.key: permission denied`                                                                                                       | The key is `0600`; the proxy container runs non-root.                                               | `chmod 644 data/tls.key`.                                                                                                                                             |23| `curl https://<proxy>:8080` fails with `wrong version number`                                                                                                  | Expected; the listener is plaintext WebSocket. TLS happens inside the WS stream.                    | Verify through a [Managed Agent or the Messages API](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers) instead. |2425The following sections cover failures that need more than a one-line fix.2627## OAuth fails behind a source-IP allowlist2829OAuth flows fail when your authorization server's source-IP allowlist blocks Anthropic's backend from reaching `/token`, `/register`, and the discovery endpoints. If you'd rather not allowlist Anthropic's egress ranges, you can route the backend-to-backend OAuth calls through the tunnel while keeping the browser-facing `/authorize` endpoint on your existing public hostname.3031<Steps>32  <Step title="Add a proxy route for the authorization server">33    ```yaml34    routes:35      mcp: http://your-mcp-server:808036      auth: http://your-auth-server:808037    ```3839    Restart the proxy after editing `routes` (`docker compose restart mcp-proxy`, or `helm upgrade`).40  </Step>4142  <Step title="Serve split-endpoint discovery metadata">43    Your authorization server's `/.well-known/oauth-authorization-server` response should point `authorization_endpoint` at your existing allowlisted hostname and everything else at the tunnel:4445    ```json46    {47      "issuer": "https://auth.<tunnel-domain>",48      "authorization_endpoint": "https://<your-allowlisted-host>/authorize",49      "token_endpoint": "https://auth.<tunnel-domain>/token",50      "registration_endpoint": "https://auth.<tunnel-domain>/register",51      "code_challenge_methods_supported": ["S256"]52    }53    ```54  </Step>5556  <Step title="Point the MCP server at the tunnel issuer">57    Your MCP server's `/.well-known/oauth-protected-resource` response should reference the tunnel hostname as its authorization server:5859    ```json60    {61      "resource": "https://mcp.<tunnel-domain>",62      "authorization_servers": ["https://auth.<tunnel-domain>"]63    }64    ```65  </Step>66</Steps>6768With this configuration, the user's browser hits `/authorize` on your existing hostname (which your allowlist already permits), while Anthropic's backend reaches `/token`, `/register`, and the discovery documents through the tunnel.6970## Setup component authentication failures7172The [setup component](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) (Helm Job or Compose `setup` service) authenticates to the Tunnels API by exchanging an OIDC JWT through your federation rule. When the exchange fails, see [Troubleshoot a failed exchange](https://platform.claude.com/docs/en/manage-claude/wif-reference#troubleshoot-a-failed-exchange) in the Workload Identity Federation reference; the failure modes (subject, audience, issuer, JWKS, lifetime) are the same.7374Tunnels-specific causes:7576* The chart's default audience is `api.anthropic.com` (no scheme). If your rule's audience is `https://api.anthropic.com`, set `api.wif.audience` to match.77* A `403` from the Tunnels API after a successful exchange means the rule's scope doesn't include `workspace:manage_tunnels`, or the rule's service account isn't a member of the tunnel's workspace. Set the scope and add the service account to the workspace.7879On Helm, the setup component runs as a pre-install hook Job. On failure, the Job is left behind for inspection (`kubectl logs job/mcp-tunnel-setup -n mcp-tunnel`). Helm doesn't manage hook resources, so delete it before retrying:8081```bash82helm uninstall mcp-tunnel -n mcp-tunnel83kubectl -n mcp-tunnel delete job mcp-tunnel-setup84```8586## Tunnel won't connect8788Check the cloudflared logs first. Common causes:8990* The `TUNNEL_TOKEN` is missing, expired, or copied incorrectly.91* A firewall is blocking outbound TCP/UDP on port 7844 to the tunnel edge.9293cloudflared may also log warnings about UDP receive buffer sizes; this is a QUIC tuning hint, not an error.9495## Certificate errors9697When Anthropic rejects the proxy's certificate during inner TLS, the proxy logs `tls handshake failed`. Verify that:9899* The server certificate has not expired.100* The certificate's Subject Alternative Name matches `*.<tunnel-domain>`.101* The signing CA is registered with Anthropic for this tunnel.102103See the [certificate requirements](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference#certificate-requirements) for the full validation rules.104105## Upstream IP validation106107For SSRF protection, the proxy only dials addresses in the RFC1918 private ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) by default. Only IPv4 is supported for the proxy-to-upstream connection. (The cloudflared-to-edge egress range in [Network requirements](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#network-requirements) is a different hop.)108109If the proxy logs `IP validation failed: <ip> is not a private address`, the upstream hostname resolved outside that set. On Kubernetes, some managed distributions allocate the Service CIDR outside RFC1918; if `kubectl get svc kubernetes -n default -o jsonpath='{.spec.clusterIP}'` returns an address outside the private ranges, look up your cluster's Service CIDR and add it.110111If the address is legitimate, add the narrowest covering CIDR to `upstream.allowed_ips`. Setting `allowed_ips` **replaces** the RFC1918 default rather than extending it, so include the private ranges your other upstream MCP servers use:112113```yaml config/mcp-proxy.yaml114upstream:115  allowed_ips:116    - 10.0.0.0/8117    - 172.16.0.0/12118    - 192.168.0.0/16119    - 127.0.0.0/8       # loopback, for local testing only120```121122<Warning>123  Avoid `0.0.0.0/0` outside of local testing; it disables SSRF protection entirely.124</Warning>125
Files main
Menu

Theme