Set up an MCP tunnel changedconnectors/mcp-tunnels/setup
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+144added
Lines−68removed
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
### Replace the Tunnels API key ### Rotate the tunnel token ### Renew the server certificate ## Next steps
The whole hunk
from line 1, old and new numbered
/
from line 1
11# Set up an MCP tunnel
22
3> Create a Tunnels API key in claude.ai, deploy the MCP tunnel stack with Helm or Docker Compose, verify the connection, add tunneled MCP servers as custom connectors, rotate the tunnel token and certificates, and remove a tunnel.
3> Create a Tunnels API key, deploy the MCP tunnel stack with Helm or Docker Compose, verify the connection, and add tunneled MCP servers as custom connectors.
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 8
88
99This page covers the full setup of an MCP tunnel for a claude.ai Enterprise organization, from creating the API key that provisioning uses to members calling a tunneled MCP server from Claude. You need the Owner or Primary Owner role in claude.ai, and someone who can deploy containers to a Kubernetes cluster or a Docker host inside your network. Read [MCP tunnels](/docs/connectors/mcp-tunnels/overview) first if the tunnel stack, the tunnel domain, and routes are unfamiliar.
1010
11The deployment steps on this page are reference deployments. You are responsible for adapting them to your organization's security requirements. For the full set of proxy options, certificate requirements, and hardening guidance, see the [MCP tunnels reference](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference) and [MCP tunnels security](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/security) pages in the Claude Platform docs. Those pages describe the Claude Console flow, which authenticates the setup component differently. For a claude.ai organization, follow the authentication steps on this page.
12
1311## Create a Tunnels API key
1412
1513The setup component that runs alongside the tunnel stack needs a short-lived credential to create the tunnel, register its certificate authority (CA) certificate with Anthropic, and fetch the tunnel token. In claude.ai that credential is a Tunnels API key.
1614
171. In claude.ai, go to **Organization settings > Tunnels**. This page appears once Anthropic has enabled MCP tunnels for your organization.
182. Open **Tunnels API** and create a key.
193. Copy the key somewhere safe for the next section. You pass it to the setup component once.
15<Steps>
16 <Step title="Open Organization settings > Tunnels">
17 In claude.ai, go to **Organization settings > Tunnels**. This page appears once Anthropic has enabled MCP tunnels for your organization.
18 </Step>
2019
20 <Step title="Create a key">
21 Open **Tunnels API** and create a key.
22 </Step>
23
24 <Step title="Copy the key">
25 Copy the key somewhere safe for the next section. You pass it to the setup component once.
26 </Step>
27</Steps>
28
2129The tunnel stack does not use the key at runtime. Revoke the key as soon as setup completes, and create a fresh one later when you rotate the tunnel token.
2230
2331## Deploy the tunnel stack
2432
33The deployment steps on this page are reference deployments. You are responsible for adapting them to your organization's security requirements. For the full set of proxy options, certificate requirements, and hardening guidance, see the [MCP tunnels reference](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference) and [MCP tunnels security](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/security) pages in the Claude Platform docs. Those pages describe the Claude Console flow, which authenticates the setup component differently. For a claude.ai organization, follow the authentication steps on this page.
34
2535Choose Helm if you run Kubernetes. The chart provisions the tunnel, stores the credentials in a Secret, and renews the server certificate automatically. Choose Docker Compose for a single host or a VM, where you run the setup component and certificate renewal yourself.
2636
27Both paths need at least one route. A route maps a subdomain of your tunnel domain to the internal URL of an MCP server, in the form `scheme://host:port` with no path. The examples use `docs` pointing at `http://docs-mcp.example.corp:8080`. Replace them with your own servers.
37Both the Helm and Docker Compose paths need at least one route. A route maps a subdomain of your tunnel domain to the internal URL of an MCP server, in the form `scheme://host:port` with no path. The examples use `docs` pointing at `http://docs-mcp.example.corp:8080`. Replace them with your own servers.
2838
2939<Tabs>
3040 <Tab title="Helm">
from line 283
273283
274284Each route becomes a custom connector for your organization. The connector URL is the route's tunnel hostname plus the path your MCP server serves. Many servers serve at `/mcp`, and the proxy forwards the path unchanged.
275285
2761. In claude.ai, go to **Organization settings > Connectors**.
2772. Select **Add**, then **Custom**. If Claude asks for the connector type, choose **Web**.
2783. Enter the server URL, for example `https://docs.abc123.tunnel.anthropic.com/mcp`.
2794. Configure authentication for the server. If its OAuth authorization server is also inside your network, turn on **Tunnel OAuth configuration** and follow [Authenticate to MCP servers behind a tunnel](/docs/connectors/mcp-tunnels/oauth).
2805. Select **Add**.
286<Steps>
287 <Step title="Open organization connectors">
288 In claude.ai, go to **Organization settings > Connectors**.
289 </Step>
281290
282Members then find the connector in their own connector settings and select **Connect** to sign in, as described in [Third party connectors with remote MCP](/docs/connectors/custom/remote-mcp#adding-custom-connectors). To confirm the tunnel end to end, connect the server yourself and ask Claude to use one of its tools while you watch the proxy logs for the request.
291 <Step title="Add a custom connector">
292 Select **Add**, then **Custom**. If Claude asks for the connector type, choose **Web**.
293 </Step>
283294
295 <Step title="Enter the tunnel URL">
296 Enter the server URL, for example `https://docs.abc123.tunnel.anthropic.com/mcp`.
297 </Step>
298
299 <Step title="Configure authentication">
300 Configure authentication for the server. If its OAuth authorization server is also inside your network, turn on **Tunnel OAuth configuration** and follow [Authenticate to MCP servers behind a tunnel](/docs/connectors/mcp-tunnels/oauth).
301 </Step>
302
303 <Step title="Add the connector">
304 Select **Add**.
305 </Step>
306</Steps>
307
308Members then find the connector in their own connector settings and select **Connect** to sign in, as described in [Add a connector by URL](/docs/connectors/custom/add-unlisted#add-a-connector-by-url). To confirm the tunnel end to end, connect the server yourself and ask Claude to use one of its tools while you watch the proxy logs for the request.
309
284310### Add more servers later
285311
286Add a route for the new server, apply the change, and register the new hostname as another custom connector. No certificate or cloudflared changes are needed, because the server certificate covers every subdomain of your tunnel domain.
312Adding another MCP server later takes a new route and a new connector. No certificate or cloudflared changes are needed, because the server certificate covers every subdomain of your tunnel domain.
287313
288<CodeGroup>
289 ```bash Helm theme={null}
290 # After adding the route under gateway.config.routes in values.yaml
291 helm upgrade mcp-tunnel \
292 oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
293 --version 2.0.2 \
294 -n mcp-tunnel \
295 -f values.yaml
296 ```
314<Steps>
315 <Step title="Add a route">
316 Add a route for the new server.
317 </Step>
297318
298 ```bash Docker Compose theme={null}
299 # After adding the route in config/mcp-proxy.yaml
300 docker compose restart mcp-proxy
301 ```
302</CodeGroup>
319 <Step title="Apply the change">
320 Apply the change:
303321
322 <CodeGroup>
323 ```bash Helm theme={null}
324 # After adding the route under gateway.config.routes in values.yaml
325 helm upgrade mcp-tunnel \
326 oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
327 --version 2.0.2 \
328 -n mcp-tunnel \
329 -f values.yaml
330 ```
331
332 ```bash Docker Compose theme={null}
333 # After adding the route in config/mcp-proxy.yaml
334 docker compose restart mcp-proxy
335 ```
336 </CodeGroup>
337 </Step>
338
339 <Step title="Register the connector">
340 Register the new hostname as another custom connector.
341 </Step>
342</Steps>
343
304344## Rotate credentials
305345
306Three credentials are involved, and each rotates differently.
346An MCP tunnel involves three credentials: the Tunnels API key, the tunnel token, and the server certificate. Each rotates differently.
307347
308**Tunnels API key.** Used only while the setup component runs. Revoke it after every use and create a new one in **Organization settings > Tunnels > Tunnels API** when you next need to run setup.
348### Replace the Tunnels API key
309349
310**Tunnel token.** Authenticates cloudflared's outbound connection. Rotate it on your regular schedule and immediately if you suspect exposure. Rotation does not sever connections that are already established, so you can rotate, restart cloudflared with the new value, and let the old connections drain.
350The Tunnels API key is used only while the setup component runs. Revoke it after every use and create a new one in **Organization settings > Tunnels > Tunnels API** when you next need to run setup.
311351
352### Rotate the tunnel token
353
354The tunnel token authenticates cloudflared's outbound connection. Rotate it on your regular schedule and immediately if you suspect exposure. Rotation does not sever connections that are already established, so you can rotate, restart cloudflared with the new value, and let the old connections drain.
355
312356<Tabs>
313357 <Tab title="Helm">
314 Increment `tunnel.tokenVersion` in `values.yaml`, create a fresh Tunnels API key, and upgrade. The setup component re-runs, rotates the token, and updates the Secret.
358 <Steps>
359 <Step title="Increment the token version">
360 Increment `tunnel.tokenVersion` in `values.yaml`.
361 </Step>
315362
316 ```bash theme={null}
317 read -rs API_TOKEN && export API_TOKEN
363 <Step title="Create a Tunnels API key">
364 Create a fresh Tunnels API key.
365 </Step>
318366
319 helm upgrade mcp-tunnel \
320 oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
321 --version 2.0.2 \
322 -n mcp-tunnel \
323 -f values.yaml \
324 --set api.token="$API_TOKEN" \
325 --set setup.force=true
326 ```
367 <Step title="Upgrade">
368 Upgrade. The setup component re-runs, rotates the token, and updates the Secret.
327369
328 Revoke the API key once the upgrade completes.
370 ```bash theme={null}
371 read -rs API_TOKEN && export API_TOKEN
372
373 helm upgrade mcp-tunnel \
374 oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
375 --version 2.0.2 \
376 -n mcp-tunnel \
377 -f values.yaml \
378 --set api.token="$API_TOKEN" \
379 --set setup.force=true
380 ```
381
382 Revoke the API key once the upgrade completes.
383 </Step>
384 </Steps>
329385 </Tab>
330386
331387 <Tab title="Docker Compose">
332 Edit `docker-compose.yaml` and increment the `--token-version` value in the `setup` service (for example from `1` to `2`), so the new value persists for future runs. Then create a fresh Tunnels API key and re-run setup.
388 <Steps>
389 <Step title="Increment the token version">
390 Edit `docker-compose.yaml` and increment the `--token-version` value in the `setup` service (for example from `1` to `2`), so the new value persists for future runs.
391 </Step>
333392
334 ```bash theme={null}
335 read -rs API_TOKEN && export API_TOKEN
336 docker compose run --rm setup
393 <Step title="Create a Tunnels API key">
394 Create a fresh Tunnels API key.
395 </Step>
337396
338 export TUNNEL_TOKEN=$(sudo cat data/tunnel-token)
339 docker compose up -d cloudflared
340 ```
397 <Step title="Re-run setup">
398 Re-run setup, then restart cloudflared with the new token:
341399
400 ```bash theme={null}
401 read -rs API_TOKEN && export API_TOKEN
402 docker compose run --rm setup
403
404 export TUNNEL_TOKEN=$(sudo cat data/tunnel-token)
405 docker compose up -d cloudflared
406 ```
407 </Step>
408 </Steps>
409
342410 Revoke the API key and run `unset API_TOKEN` once rotation completes. For a multi-host deployment, setup writes the new token only to the `data/` directory on the host where it ran, so copy the updated `data/` directory (at minimum `data/tunnel-token`) to every other host that runs a replica. Then repeat the last two commands on each of those hosts so every replica restarts with the new token.
343411 </Tab>
344412</Tabs>
345413
346**Server certificate.** The certificate the proxy presents is valid for 90 days, and you are responsible for renewing it before it expires. Renewal is local. It signs a new certificate with the CA already stored in your deployment, makes no API calls, and needs no API key. The proxy reloads the certificate file automatically, so no restart is required.
414### Renew the server certificate
347415
416The server certificate the proxy presents is valid for 90 days, and you are responsible for renewing it before it expires. Renewal is local. It signs a new certificate with the CA already stored in your deployment, makes no API calls, and needs no API key. The proxy reloads the certificate file automatically, so no restart is required.
417
348418<Tabs>
349419 <Tab title="Helm">
350420 The chart deploys a CronJob that runs daily and renews the certificate once it is within 30 days of expiry. Monitor the CronJob and the certificate's expiry date to confirm renewal completes.
from line 493
423493</Steps>
424494
425495If you archived the tunnel because of a suspected compromise, also notify your Anthropic account team, rotate any OAuth tokens or secrets your MCP servers issued, and review the proxy, cloudflared, and MCP server logs for the affected period before you provision a replacement tunnel.
496
497## Next steps
498
499* [Authenticate to MCP servers behind a tunnel](/docs/connectors/mcp-tunnels/oauth): make OAuth sign-in work when your authorization server is inside your network
500* [Troubleshoot MCP tunnels](/docs/connectors/mcp-tunnels/troubleshooting): diagnose connection, certificate, routing, and sign-in failures
501* [MCP tunnels reference](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference): proxy configuration fields, certificate requirements, and the setup component
426502
No line in this hunk matches that.