troubleshooting changedagents-and-tools/mcp-tunnels/troubleshooting
Nearest release: v2.1.307, published an hour after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+4added
Lines−4removed
From line
20
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits3to this page, all time
The whole hunk
from line 20, old and new numbered
/
from line 20
2020| 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). |
2121| Proxy exits with `cannot unmarshal !!seq into map[string]string` | `routes` is a YAML list. | Use `routes: { name: http://host:port }`. |
2222| 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. |
23| `curl https://<proxy>:8080` fails with `wrong version number` | Expected; the listener is plaintext WebSocket. TLS occurs 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. |
2424
2525The following sections cover failures that need more than a one-line fix.
2626
2727## OAuth fails behind a source-IP allowlist
2828
29OAuth 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.
29OAuth flows fail when your authorization server's source-IP allowlist blocks Anthropic's back end 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.
3030
3131<Steps>
3232 <Step title="Add a proxy route for the authorization server">
from line 65
6565 </Step>
6666</Steps>
6767
68With 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.
68With this configuration, the user's browser requests `/authorize` on your existing hostname (which your allowlist already includes), whereas Anthropic's back end reaches `/token`, `/register`, and the discovery documents through the tunnel.
6969
7070## Setup component authentication failures
7171
from line 90
9090* The `TUNNEL_TOKEN` is missing, expired, or copied incorrectly.
9191* A firewall is blocking outbound TCP/UDP on port 7844 to the tunnel edge.
9292
93cloudflared may also log warnings about UDP receive buffer sizes; this is a QUIC tuning hint, not an error.
93cloudflared might also log warnings about UDP receive buffer sizes; this is a QUIC tuning hint, not an error.
9494
9595## Certificate errors
9696
No line in this hunk matches that.