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 20 Oct 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+26added
Lines−30removed
From line
2
where the diff opens
First seen
31 Aug 2026
this site's first read of the page
Recorded edits5to this page, all time
The whole hunk
from line 2, old and new numbered
/
from line 2
22
33> 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
5<Note>
6 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.
7</Note>
5> [!NOTE]
6>
7> 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.
88
99A request through an [MCP tunnel](/docs/connectors/mcp-tunnels/overview) can fail at three points, and it helps to check them in order. First the outbound connection from cloudflared to the tunnel edge, then the inner TLS handshake between Anthropic and your proxy, then the proxy's routing to your MCP server. The cloudflared and proxy logs on your side show which point a request reached. If the proxy logs nothing at all for a request, it never arrived in your network.
1010
11<CodeGroup>
12 ```bash Helm theme={null}
13 kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c cloudflared
14 kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c mcp-proxy
15 ```
11```bash Helm theme={null}
12kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c cloudflared
13kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c mcp-proxy
14```
1615
17 ```bash Docker Compose theme={null}
18 docker compose logs cloudflared
19 docker compose logs mcp-proxy
20 ```
21</CodeGroup>
16```bash Docker Compose theme={null}
17docker compose logs cloudflared
18docker compose logs mcp-proxy
19```
2220
2321For proxy configuration fields and certificate rules referenced below, see the [MCP tunnels reference](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference). The [platform troubleshooting guide](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting) covers the same stack and applies to claude.ai tunnels as well, apart from its Console-specific steps.
2422
from line 80
8280 - 100.64.12.0/22 # example: a cluster Service range outside RFC 1918
8381```
8482
85<Warning>
86 Don't set `0.0.0.0/0` or `disable_ip_validation` outside of isolated testing. IP validation is the proxy's protection against server-side request forgery.
87</Warning>
83> [!WARNING]
84>
85> Don't set `0.0.0.0/0` or `disable_ip_validation` outside of isolated testing. IP validation is the proxy's protection against server-side request forgery.
8886
8987### Proxy exits with `cannot unmarshal !!seq into map[string]string`
9088
from line 102
104102
105103Work through these checks in order.
106104
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>
105**1. Confirm the stack is connected**
111106
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>
107Confirm the stack is connected, using the log checks in [Verify the connection](/docs/connectors/mcp-tunnels/setup#verify-the-connection).
115108
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>
109**2. Confirm the tunnel's organization**
119110
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>
111Confirm 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.
112
113**3. Confirm the connector URL's path**
114
115Confirm 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`.
116
117**4. Watch the proxy logs**
118
119Watch 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.
124120
125121## OAuth sign-in
126122
No line in this hunk matches that.