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 22 Oct 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+8added
Lines−8removed
From line
39
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 39, old and new numbered
/
from line 39
3939
4040### Setup fails with `Organization already has the maximum of 10 non-archived Tunnels`
4141
42Each organization can have at most 10 tunnels that are not archived, and every setup run with an empty `tunnel.id` (Helm) or no `--tunnel-id` (Docker Compose) creates a new one. Archive tunnels you no longer use, as described in [Remove a tunnel](/docs/connectors/mcp-tunnels/setup#remove-a-tunnel), then run setup again. To attach a new deployment to an existing tunnel instead of creating one, set `tunnel.id` in `values.yaml` or pass `--tunnel-id` to the setup command.
42Each organization can have at most 10 tunnels that are not archived, and every setup run with an empty `tunnel.id` (Helm) or no `--tunnel-id` (Docker Compose) creates a new one. Archive tunnels you no longer use, as described in [Remove a tunnel](/docs/connectors/mcp-tunnels/setup.md#remove-a-tunnel), then run setup again. To attach a new deployment to an existing tunnel instead of creating one, set `tunnel.id` in `values.yaml` or pass `--tunnel-id` to the setup command.
4343
4444### Helm install fails with a hook error
4545
from line 94
9494
9595### Proxy logs `tls handshake failed`
9696
97Anthropic rejected the certificate the proxy presented. Check that the server certificate has not passed its 90-day validity, that its Subject Alternative Name covers `*.<your-tunnel-domain>`, and that it was signed by the CA the setup component registered for this tunnel. On Docker Compose, also confirm the files in `data/` are readable by user ID `65532`. To renew an expired certificate, see [Rotate credentials](/docs/connectors/mcp-tunnels/setup#rotate-credentials).
97Anthropic rejected the certificate the proxy presented. Check that the server certificate has not passed its 90-day validity, that its Subject Alternative Name covers `*.<your-tunnel-domain>`, and that it was signed by the CA the setup component registered for this tunnel. On Docker Compose, also confirm the files in `data/` are readable by user ID `65532`. To renew an expired certificate, see [Rotate credentials](/docs/connectors/mcp-tunnels/setup.md#rotate-credentials).
9898
9999## Connectors and tools
100100
from line 104
104104
105105**1. Confirm the stack is connected**
106106
107Confirm the stack is connected, using the log checks in [Verify the connection](/docs/connectors/mcp-tunnels/setup#verify-the-connection).
107Confirm the stack is connected, using the log checks in [Verify the connection](/docs/connectors/mcp-tunnels/setup.md#verify-the-connection).
108108
109109**2. Confirm the tunnel's organization**
110110
from line 120
120120
121121## OAuth sign-in
122122
123See [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.
123See [Authenticate to MCP servers behind a tunnel](/docs/connectors/mcp-tunnels/oauth.md) for how the sign-in flow splits between the member's browser and Claude's servers.
124124
125125### Sign-in redirects to a tunnel address that does not load
126126
127The authorization server's metadata advertises an authorization endpoint on the `tunnel.anthropic.com` hostname or an internal hostname, and the member's browser can't load it. Turn on **Tunnel OAuth configuration** for the connector and set **Authorization endpoint** to the sign-in URL members' browsers can reach, or publish split metadata from the authorization server. Both are described on the [OAuth page](/docs/connectors/mcp-tunnels/oauth#set-the-tunnel-oauth-configuration).
127The authorization server's metadata advertises an authorization endpoint on the `tunnel.anthropic.com` hostname or an internal hostname, and the member's browser can't load it. Turn on **Tunnel OAuth configuration** for the connector and set **Authorization endpoint** to the sign-in URL members' browsers can reach, or publish split metadata from the authorization server. Both are described on the [OAuth page](/docs/connectors/mcp-tunnels/oauth.md#set-the-tunnel-oauth-configuration).
128128
129129### Sign-in succeeds in the browser but the connector never connects
130130
from line 132
132132
133133### The Token endpoint field rejects the URL
134134
135**Token endpoint** and **Registration endpoint** accept an `https://` URL that is either under `tunnel.anthropic.com` or on the same origin (scheme, host, and port) as the **Authorization endpoint**. Any other URL is rejected, because Claude sends the token exchange and the client credentials to it. Add a route for your authorization server as shown in [Route the authorization server through the tunnel](/docs/connectors/mcp-tunnels/oauth#route-the-authorization-server-through-the-tunnel) and enter the resulting tunnel URL. The **Authorization endpoint** field has no such restriction, because browsers load it directly.
135**Token endpoint** and **Registration endpoint** accept an `https://` URL that is either under `tunnel.anthropic.com` or on the same origin (scheme, host, and port) as the **Authorization endpoint**. Any other URL is rejected, because Claude sends the token exchange and the client credentials to it. Add a route for your authorization server as shown in [Route the authorization server through the tunnel](/docs/connectors/mcp-tunnels/oauth.md#route-the-authorization-server-through-the-tunnel) and enter the resulting tunnel URL. The **Authorization endpoint** field has no such restriction, because browsers load it directly.
136136
137137### The Tunnel OAuth configuration toggle is missing
138138
from line 144
144144
145145## Related resources
146146
147* [Set up an MCP tunnel](/docs/connectors/mcp-tunnels/setup): the deployment, verification, and credential rotation steps
148* [Authenticate to MCP servers behind a tunnel](/docs/connectors/mcp-tunnels/oauth): the Tunnel OAuth configuration fields and the split-metadata alternative
147* [Set up an MCP tunnel](/docs/connectors/mcp-tunnels/setup.md): the deployment, verification, and credential rotation steps
148* [Authenticate to MCP servers behind a tunnel](/docs/connectors/mcp-tunnels/oauth.md): the Tunnel OAuth configuration fields and the split-metadata alternative
149149* [MCP tunnels reference](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference): proxy configuration fields, certificate requirements, and the setup component
150150
No line in this hunk matches that.