Troubleshoot MCP tunnels changedconnectors/mcp-tunnels/troubleshooting
Nearest release: v2.1.283, published under an hour after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 25 Sep 2026 18:00 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 25 Sep 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+31added
Lines−9removed
From line
1
where the diff opens
First seen
31 Aug 2026
this site's first read of the page
Recorded edits3to this page, all time
### Adding the connector fails, or the connector connects but no tools appear ## Related resources ### Adding the connector fails, or it connects but no tools appear
The whole hunk
from line 1, old and new numbered
/
from line 1
11# Troubleshoot MCP tunnels
22
3> Fix MCP tunnel problems: cloudflared won't connect, connector added but tools don't appear, no route for host, IP validation failed, TLS handshake failed, expired certificate, OAuth sign-in redirects to a tunnel.anthropic.com URL, token exchange fails, and setup or Helm hook errors.
3> Fix MCP tunnel problems: cloudflared won't connect, tools don't appear, routing and IP validation errors, TLS and certificate failures, and OAuth errors.
44
55<Note>
66 MCP tunnels are in research preview and are available to organizations on the Claude Enterprise plan by request. To request access, [submit the MCP tunnels interest form](https://claude.com/form/mcp-tunnels) or contact your Anthropic account team.
from line 26
2626
2727### The tunnel stack starts but cloudflared never connects
2828
29cloudflared logs four `Registered tunnel connection` lines when it reaches the tunnel edge. If they never appear, the cause is almost always one of two things. Either `TUNNEL_TOKEN` is missing, truncated, or from a token that has since been rotated, or a firewall is blocking outbound TCP and UDP on port 7844 to the edge ranges `198.41.192.0/19` and `2606:4700:a0::/44`. On Docker Compose, confirm the variable is exported in the shell that ran `docker compose up`. After a token rotation, restart cloudflared on every host with the new value.
29cloudflared logs four `Registered tunnel connection` lines when it reaches the tunnel edge. If they never appear, the cause is almost always one of these:
3030
31* **The tunnel token**: `TUNNEL_TOKEN` is missing, truncated, or from a token that has since been rotated. On Docker Compose, confirm the variable is exported in the shell that ran `docker compose up`. After a token rotation, restart cloudflared on every host with the new value
32* **A firewall**: a firewall is blocking outbound TCP and UDP on port 7844 to the edge ranges `198.41.192.0/19` and `2606:4700:a0::/44`
33
3134### cloudflared logs `failed to sufficiently increase receive buffer size`
3235
33This is a QUIC tuning hint, not an error, and the tunnel works without addressing it. To remove the warning, raise the host's UDP buffer limits as described in the [quic-go UDP buffer documentation](https://github.com/quic-go/quic-go/wiki/UDP-Buffer-Sizes).
36The `failed to sufficiently increase receive buffer size` message is a QUIC tuning hint, not an error, and the tunnel works without addressing it. To remove the warning, raise the host's UDP buffer limits as described in the [quic-go UDP buffer documentation](https://github.com/quic-go/quic-go/wiki/UDP-Buffer-Sizes).
3437
3538### The setup component fails with an authentication or permission error
3639
from line 55
5255
5356### A tunnel hostname does not respond to curl or a browser
5457
55This is expected. Hostnames under `tunnel.anthropic.com` accept connections only from Claude, so you can't test them from your own network or the internet. Verify the tunnel by connecting the custom connector in Claude and calling one of the server's tools while you watch the proxy logs.
58A tunnel hostname that doesn't respond to curl or a browser is expected. Hostnames under `tunnel.anthropic.com` accept connections only from Claude, so you can't test them from your own network or the internet. Verify the tunnel by connecting the custom connector in Claude and calling one of the server's tools while you watch the proxy logs.
5659
5760## Routes and certificates
5861
from line 100
97100
98101## Connectors and tools
99102
100### Adding the connector fails, or it connects but no tools appear
103### Adding the connector fails, or the connector connects but no tools appear
101104
102105Work through these checks in order.
103106
1041. Confirm the stack is connected, using the log checks in [Verify the connection](/docs/connectors/mcp-tunnels/setup#verify-the-connection).
1052. Confirm the tunnel was created with a Tunnels API key from the same claude.ai organization where you are adding the connector. A tunnel created from another organization, including a Claude Console organization, is refused before any traffic reaches your network, and your proxy logs show nothing.
1063. Confirm the connector URL includes the path your MCP server serves, such as `/mcp`. A request to the bare hostname reaches the proxy but the server may answer `404`.
1074. Watch the proxy logs while you retry. `no route for host` and `IP validation failed` point to the sections above. An upstream connection error means the proxy can't reach the MCP server from where it runs.
107<Steps>
108 <Step title="Confirm the stack is connected">
109 Confirm the stack is connected, using the log checks in [Verify the connection](/docs/connectors/mcp-tunnels/setup#verify-the-connection).
110 </Step>
108111
112 <Step title="Confirm the tunnel's organization">
113 Confirm the tunnel was created with a Tunnels API key from the same claude.ai organization where you are adding the connector. A tunnel created from another organization, including a Claude Console organization, is refused before any traffic reaches your network, and your proxy logs show nothing.
114 </Step>
115
116 <Step title="Confirm the connector URL's path">
117 Confirm the connector URL includes the path your MCP server serves, such as `/mcp`. A request to the bare hostname reaches the proxy but the server may answer `404`.
118 </Step>
119
120 <Step title="Watch the proxy logs">
121 Watch the proxy logs while you retry. `no route for host` and `IP validation failed` point to the sections above. An upstream connection error means the proxy can't reach the MCP server from where it runs.
122 </Step>
123</Steps>
124
109125## OAuth sign-in
110126
111127See [Authenticate to MCP servers behind a tunnel](/docs/connectors/mcp-tunnels/oauth) for how the sign-in flow splits between the member's browser and Claude's servers.
from line 145
129145## Get help
130146
131147If these steps don't resolve the problem, contact your Anthropic account team with the tunnel domain, the time of a failed request, and the relevant cloudflared and proxy log lines.
148
149## Related resources
150
151* [Set up an MCP tunnel](/docs/connectors/mcp-tunnels/setup): the deployment, verification, and credential rotation steps
152* [Authenticate to MCP servers behind a tunnel](/docs/connectors/mcp-tunnels/oauth): the Tunnel OAuth configuration fields and the split-metadata alternative
153* [MCP tunnels reference](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference): proxy configuration fields, certificate requirements, and the setup component
132154
No line in this hunk matches that.