Set up an MCP tunnel changedconnectors/mcp-tunnels/setup
Nearest release: v2.1.305, published 2 hours 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 20 Oct 2026 17:01 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 30 Oct 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+280added
Lines−280removed
From line
34
where the diff opens
First seen
31 Aug 2026
this site's first read of the page
Recorded edits8to this page, all time
The whole hunk
from line 34, old and new numbered
/
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 34
3434
3535Both 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.
3636
37**Helm**
38
39**1. Fetch the default values**
40
41```bash theme={null}
42helm show values \
43 oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
44 --version 2.1.0 > values.yaml
45```
46
47The file includes comments explaining each field.
48
49**2. Configure routes**
50
51Edit `values.yaml` and add a `routes` entry under `gateway.config` for each MCP server. Leave `tunnel.id` empty so the setup component creates the tunnel during install.
52
53```yaml values.yaml theme={null}
54tunnel:
55 id: ""
56 # Increment to rotate the tunnel token on a later upgrade.
57 tokenVersion: "1"
58
59gateway:
60 config:
61 routes:
62 docs: http://docs-mcp.example.corp:8080
63 search: http://10.0.12.7:9000
64```
65
66With these routes, Claude reaches the servers at `docs.<your-tunnel-domain>` and `search.<your-tunnel-domain>`. If a route targets an address outside the RFC 1918 private ranges (some managed Kubernetes distributions allocate Service IPs elsewhere), add the range under `gateway.config.upstream.allowed_ips` as described in [Troubleshooting](https://claude.com/docs/connectors/mcp-tunnels/troubleshooting.md#proxy-logs-ip-validation-failed).
67
68**3. Review the rendered manifests**
69
70Render the chart with a placeholder key and review the output according to your organization's practices for third-party manifests. Rendering makes no API calls.
71
72```bash theme={null}
73helm template mcp-tunnel \
74 oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
75 --version 2.1.0 \
76 -n mcp-tunnel \
77 -f values.yaml \
78 --set api.token=placeholder > rendered.yaml
79```
80
81**4. Install**
82
83Read the Tunnels API key into an environment variable so it stays out of your shell history and values file, then install into a dedicated namespace.
84
85```bash theme={null}
86# Paste the Tunnels API key (input is hidden)
87read -rs API_TOKEN && export API_TOKEN
88
89helm install mcp-tunnel \
90 oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
91 --version 2.1.0 \
92 --namespace mcp-tunnel --create-namespace \
93 -f values.yaml \
94 --set api.token="$API_TOKEN"
95```
96
97The setup component runs as a pre-install hook, so `helm install` blocks until the tunnel is created, the CA is registered, and the credentials are stored in the `mcp-tunnel` Secret. If the install fails with a hook error, see [Troubleshooting](https://claude.com/docs/connectors/mcp-tunnels/troubleshooting.md#helm-install-fails-with-a-hook-error).
98
99> [!WARNING]
100>
101> Revoke the Tunnels API key in **Organization settings > Tunnels > Tunnels API** as soon as the install completes. Helm records `--set` values in its release history Secrets, and Kubernetes Secrets are not encrypted at rest by default, so the key remains recoverable from the cluster until you revoke it.
102
103**5. Read the tunnel domain**
104
105You need the tunnel domain to add connectors later.
106
107```bash theme={null}
108kubectl -n mcp-tunnel get secret mcp-tunnel \
109 -o jsonpath='{.data.tunnel-domain}' | base64 -d
110```
111
112The value looks like `abc123.tunnel.anthropic.com`.
113
114To restrict the pod's egress at the network level, set `networkPolicy.enabled: true` in `values.yaml` and list your MCP servers under `networkPolicy.mcpServers`. The policy already allows cloudflared to reach the tunnel edge. Your cluster's network plugin must support NetworkPolicy.
115
116For later configuration changes such as routes or replica count, edit `values.yaml` and run `helm upgrade` with the same `--version` and `-f values.yaml`, without the API key. Keep a complete `values.yaml` rather than relying on `--reuse-values`, because Helm's deep merge can silently keep a route you deleted.
117
118**Docker Compose**
119
120**1. Prepare the deployment directory**
121
122```bash theme={null}
123mkdir -p mcp-tunnel/{config,data}
124cd mcp-tunnel
125sudo chown 65532:65532 data
126```
127
128The containers run as the non-root user ID `65532` and need write access to `data/`.
129
130**2. Write docker-compose.yaml**
131
132The compose file pins images by digest, runs every container as non-root with a read-only filesystem, drops all Linux capabilities, and disables privilege escalation.
133
134```bash theme={null}
135cat > docker-compose.yaml <<'EOF'
136services:
137 # One-time provisioning. Run with: docker compose run --rm setup
138 setup:
139 image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:d243d30642d39857a0579e465cb3b9bf3ae7c1141e83143bb6856777a31467a5
140 entrypoint: ["/setup"]
141 command:
142 - init
143 - --api-url=https://api.anthropic.com
144 - --output=dir:/data
145 - --token-version=1
146 environment:
147 - API_TOKEN
148 volumes:
149 - ./data:/data
150 user: "65532:65532"
151 read_only: true
152 security_opt:
153 - no-new-privileges:true
154 cap_drop:
155 - ALL
156 profiles: ["setup"]
157
158 cloudflared:
159 image: cloudflare/cloudflared@sha256:0e56c13c7058fcef9c4f0e7d83372f82330548dbf8f8b366f3d8b506526d93b2
160 command: tunnel --no-autoupdate run --url http://localhost:8080
161 environment:
162 - TUNNEL_TOKEN
163 # Share the proxy's network namespace so localhost:8080 reaches it.
164 network_mode: "service:mcp-proxy"
165 restart: unless-stopped
166 user: "65532:65532"
167 read_only: true
168 security_opt:
169 - no-new-privileges:true
170 cap_drop:
171 - ALL
172 stop_grace_period: 30s
173 logging:
174 options:
175 max-size: "10m"
176 max-file: "3"
177
178 mcp-proxy:
179 image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:d243d30642d39857a0579e465cb3b9bf3ae7c1141e83143bb6856777a31467a5
180 volumes:
181 - ./config/mcp-proxy.yaml:/etc/mcp-gateway/config.yaml:ro
182 - ./data:/data:ro
183 restart: unless-stopped
184 user: "65532:65532"
185 read_only: true
186 security_opt:
187 - no-new-privileges:true
188 cap_drop:
189 - ALL
190 # Match shutdown_timeout in the proxy config
191 stop_grace_period: 30s
192 logging:
193 options:
194 max-size: "10m"
195 max-file: "3"
196EOF
197```
198
199**3. Provision the tunnel**
200
201Read the Tunnels API key into an environment variable, then run the setup component. It creates the tunnel, generates the CA and server certificate, registers the CA with Anthropic, fetches the tunnel token, and writes everything to `data/`.
202
203```bash theme={null}
204# Paste the Tunnels API key (input is hidden)
205read -rs API_TOKEN && export API_TOKEN
206
207docker compose run --rm setup
208```
209
210Read the tunnel domain and keep it for later steps.
211
212```bash theme={null}
213export TUNNEL_DOMAIN=$(sudo cat data/tunnel-domain)
214echo "$TUNNEL_DOMAIN"
215```
216
217> [!WARNING]
218>
219> Revoke the Tunnels API key in **Organization settings > Tunnels > Tunnels API** before continuing, and run `unset API_TOKEN`. The stack does not need the key at runtime.
220
221**4. Write the proxy config**
222
223`tunnel_domain` is required so the proxy can strip the domain from incoming hostnames and look up the remaining subdomain in `routes`. `routes` is a map, not a list.
224
225```bash theme={null}
226cat > config/mcp-proxy.yaml <<EOF
227listen_addr: ":8080"
228log_level: info
229shutdown_timeout: 30s
230tunnel_domain: ${TUNNEL_DOMAIN}
231tls:
232 cert_file: /data/tls.crt
233 key_file: /data/tls.key
234routes:
235 docs: http://docs-mcp.example.corp:8080
236 search: http://10.0.12.7:9000
237upstream:
238 allowed_ips:
239 - 10.0.0.0/8
240EOF
241```
242
243`upstream.allowed_ips` is the proxy's protection against server-side request forgery. Use the narrowest ranges that cover your MCP servers. Setting it replaces the RFC 1918 default rather than extending it.
244
245**5. Start the stack**
246
247```bash theme={null}
248export TUNNEL_TOKEN=$(sudo cat data/tunnel-token)
249docker compose up -d
250```
251
252The compose file reads `TUNNEL_TOKEN` from the host environment with no default, so repeat the export in every fresh shell and after a reboot. For a multi-host deployment, copy the `mcp-tunnel/` directory to each host and start it the same way. The same tunnel token and certificates work across all replicas.
253
254The `data/` directory now holds the tunnel ID, tunnel domain, tunnel token, CA key pair, and server key pair. Protect it with your organization's file-permission, encryption-at-rest, and secrets-management controls, and consider moving `ca.key` and `tunnel-token` to secure storage.
37> [tab] Helm
38>
39> **1. Fetch the default values**
40>
41> ```bash theme={null}
42> helm show values \
43> oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
44> --version 2.1.0 > values.yaml
45> ```
46>
47> The file includes comments explaining each field.
48>
49> **2. Configure routes**
50>
51> Edit `values.yaml` and add a `routes` entry under `gateway.config` for each MCP server. Leave `tunnel.id` empty so the setup component creates the tunnel during install.
52>
53> ```yaml values.yaml theme={null}
54> tunnel:
55> id: ""
56> # Increment to rotate the tunnel token on a later upgrade.
57> tokenVersion: "1"
58>
59> gateway:
60> config:
61> routes:
62> docs: http://docs-mcp.example.corp:8080
63> search: http://10.0.12.7:9000
64> ```
65>
66> With these routes, Claude reaches the servers at `docs.<your-tunnel-domain>` and `search.<your-tunnel-domain>`. If a route targets an address outside the RFC 1918 private ranges (some managed Kubernetes distributions allocate Service IPs elsewhere), add the range under `gateway.config.upstream.allowed_ips` as described in [Troubleshooting](https://claude.com/docs/connectors/mcp-tunnels/troubleshooting.md#proxy-logs-ip-validation-failed).
67>
68> **3. Review the rendered manifests**
69>
70> Render the chart with a placeholder key and review the output according to your organization's practices for third-party manifests. Rendering makes no API calls.
71>
72> ```bash theme={null}
73> helm template mcp-tunnel \
74> oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
75> --version 2.1.0 \
76> -n mcp-tunnel \
77> -f values.yaml \
78> --set api.token=placeholder > rendered.yaml
79> ```
80>
81> **4. Install**
82>
83> Read the Tunnels API key into an environment variable so it stays out of your shell history and values file, then install into a dedicated namespace.
84>
85> ```bash theme={null}
86> # Paste the Tunnels API key (input is hidden)
87> read -rs API_TOKEN && export API_TOKEN
88>
89> helm install mcp-tunnel \
90> oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
91> --version 2.1.0 \
92> --namespace mcp-tunnel --create-namespace \
93> -f values.yaml \
94> --set api.token="$API_TOKEN"
95> ```
96>
97> The setup component runs as a pre-install hook, so `helm install` blocks until the tunnel is created, the CA is registered, and the credentials are stored in the `mcp-tunnel` Secret. If the install fails with a hook error, see [Troubleshooting](https://claude.com/docs/connectors/mcp-tunnels/troubleshooting.md#helm-install-fails-with-a-hook-error).
98>
99> > [!WARNING]
100> >
101> > Revoke the Tunnels API key in **Organization settings > Tunnels > Tunnels API** as soon as the install completes. Helm records `--set` values in its release history Secrets, and Kubernetes Secrets are not encrypted at rest by default, so the key remains recoverable from the cluster until you revoke it.
102>
103> **5. Read the tunnel domain**
104>
105> You need the tunnel domain to add connectors later.
106>
107> ```bash theme={null}
108> kubectl -n mcp-tunnel get secret mcp-tunnel \
109> -o jsonpath='{.data.tunnel-domain}' | base64 -d
110> ```
111>
112> The value looks like `abc123.tunnel.anthropic.com`.
113>
114> To restrict the pod's egress at the network level, set `networkPolicy.enabled: true` in `values.yaml` and list your MCP servers under `networkPolicy.mcpServers`. The policy already allows cloudflared to reach the tunnel edge. Your cluster's network plugin must support NetworkPolicy.
115>
116> For later configuration changes such as routes or replica count, edit `values.yaml` and run `helm upgrade` with the same `--version` and `-f values.yaml`, without the API key. Keep a complete `values.yaml` rather than relying on `--reuse-values`, because Helm's deep merge can silently keep a route you deleted.
117
118> [tab] Docker Compose
119>
120> **1. Prepare the deployment directory**
121>
122> ```bash theme={null}
123> mkdir -p mcp-tunnel/{config,data}
124> cd mcp-tunnel
125> sudo chown 65532:65532 data
126> ```
127>
128> The containers run as the non-root user ID `65532` and need write access to `data/`.
129>
130> **2. Write docker-compose.yaml**
131>
132> The compose file pins images by digest, runs every container as non-root with a read-only filesystem, drops all Linux capabilities, and disables privilege escalation.
133>
134> ```bash theme={null}
135> cat > docker-compose.yaml <<'EOF'
136> services:
137> # One-time provisioning. Run with: docker compose run --rm setup
138> setup:
139> image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:d243d30642d39857a0579e465cb3b9bf3ae7c1141e83143bb6856777a31467a5
140> entrypoint: ["/setup"]
141> command:
142> - init
143> - --api-url=https://api.anthropic.com
144> - --output=dir:/data
145> - --token-version=1
146> environment:
147> - API_TOKEN
148> volumes:
149> - ./data:/data
150> user: "65532:65532"
151> read_only: true
152> security_opt:
153> - no-new-privileges:true
154> cap_drop:
155> - ALL
156> profiles: ["setup"]
157>
158> cloudflared:
159> image: cloudflare/cloudflared@sha256:0e56c13c7058fcef9c4f0e7d83372f82330548dbf8f8b366f3d8b506526d93b2
160> command: tunnel --no-autoupdate run --url http://localhost:8080
161> environment:
162> - TUNNEL_TOKEN
163> # Share the proxy's network namespace so localhost:8080 reaches it.
164> network_mode: "service:mcp-proxy"
165> restart: unless-stopped
166> user: "65532:65532"
167> read_only: true
168> security_opt:
169> - no-new-privileges:true
170> cap_drop:
171> - ALL
172> stop_grace_period: 30s
173> logging:
174> options:
175> max-size: "10m"
176> max-file: "3"
177>
178> mcp-proxy:
179> image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:d243d30642d39857a0579e465cb3b9bf3ae7c1141e83143bb6856777a31467a5
180> volumes:
181> - ./config/mcp-proxy.yaml:/etc/mcp-gateway/config.yaml:ro
182> - ./data:/data:ro
183> restart: unless-stopped
184> user: "65532:65532"
185> read_only: true
186> security_opt:
187> - no-new-privileges:true
188> cap_drop:
189> - ALL
190> # Match shutdown_timeout in the proxy config
191> stop_grace_period: 30s
192> logging:
193> options:
194> max-size: "10m"
195> max-file: "3"
196> EOF
197> ```
198>
199> **3. Provision the tunnel**
200>
201> Read the Tunnels API key into an environment variable, then run the setup component. It creates the tunnel, generates the CA and server certificate, registers the CA with Anthropic, fetches the tunnel token, and writes everything to `data/`.
202>
203> ```bash theme={null}
204> # Paste the Tunnels API key (input is hidden)
205> read -rs API_TOKEN && export API_TOKEN
206>
207> docker compose run --rm setup
208> ```
209>
210> Read the tunnel domain and keep it for later steps.
211>
212> ```bash theme={null}
213> export TUNNEL_DOMAIN=$(sudo cat data/tunnel-domain)
214> echo "$TUNNEL_DOMAIN"
215> ```
216>
217> > [!WARNING]
218> >
219> > Revoke the Tunnels API key in **Organization settings > Tunnels > Tunnels API** before continuing, and run `unset API_TOKEN`. The stack does not need the key at runtime.
220>
221> **4. Write the proxy config**
222>
223> `tunnel_domain` is required so the proxy can strip the domain from incoming hostnames and look up the remaining subdomain in `routes`. `routes` is a map, not a list.
224>
225> ```bash theme={null}
226> cat > config/mcp-proxy.yaml <<EOF
227> listen_addr: ":8080"
228> log_level: info
229> shutdown_timeout: 30s
230> tunnel_domain: ${TUNNEL_DOMAIN}
231> tls:
232> cert_file: /data/tls.crt
233> key_file: /data/tls.key
234> routes:
235> docs: http://docs-mcp.example.corp:8080
236> search: http://10.0.12.7:9000
237> upstream:
238> allowed_ips:
239> - 10.0.0.0/8
240> EOF
241> ```
242>
243> `upstream.allowed_ips` is the proxy's protection against server-side request forgery. Use the narrowest ranges that cover your MCP servers. Setting it replaces the RFC 1918 default rather than extending it.
244>
245> **5. Start the stack**
246>
247> ```bash theme={null}
248> export TUNNEL_TOKEN=$(sudo cat data/tunnel-token)
249> docker compose up -d
250> ```
251>
252> The compose file reads `TUNNEL_TOKEN` from the host environment with no default, so repeat the export in every fresh shell and after a reboot. For a multi-host deployment, copy the `mcp-tunnel/` directory to each host and start it the same way. The same tunnel token and certificates work across all replicas.
253>
254> The `data/` directory now holds the tunnel ID, tunnel domain, tunnel token, CA key pair, and server key pair. Protect it with your organization's file-permission, encryption-at-rest, and secrets-management controls, and consider moving `ca.key` and `tunnel-token` to secure storage.
255255
256256## Verify the connection
257257
from line 337
337337
338338The 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.
339339
340**Helm**
341
342**1. Increment the token version**
343
344Increment `tunnel.tokenVersion` in `values.yaml`.
345
346**2. Create a Tunnels API key**
347
348Create a fresh Tunnels API key.
349
350**3. Upgrade**
351
352Upgrade. The setup component re-runs, rotates the token, and updates the Secret.
353
354```bash theme={null}
355read -rs API_TOKEN && export API_TOKEN
356
357helm upgrade mcp-tunnel \
358 oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
359 --version 2.1.0 \
360 -n mcp-tunnel \
361 -f values.yaml \
362 --set api.token="$API_TOKEN" \
363 --set setup.force=true
364```
365
366Revoke the API key once the upgrade completes.
367
368**Docker Compose**
369
370**1. Increment the token version**
371
372Edit `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.
373
374**2. Create a Tunnels API key**
375
376Create a fresh Tunnels API key.
377
378**3. Re-run setup**
379
380Re-run setup, then restart cloudflared with the new token:
381
382```bash theme={null}
383read -rs API_TOKEN && export API_TOKEN
384docker compose run --rm setup
385
386export TUNNEL_TOKEN=$(sudo cat data/tunnel-token)
387docker compose up -d cloudflared
388```
389
390Revoke 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.
340> [tab] Helm
341>
342> **1. Increment the token version**
343>
344> Increment `tunnel.tokenVersion` in `values.yaml`.
345>
346> **2. Create a Tunnels API key**
347>
348> Create a fresh Tunnels API key.
349>
350> **3. Upgrade**
351>
352> Upgrade. The setup component re-runs, rotates the token, and updates the Secret.
353>
354> ```bash theme={null}
355> read -rs API_TOKEN && export API_TOKEN
356>
357> helm upgrade mcp-tunnel \
358> oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
359> --version 2.1.0 \
360> -n mcp-tunnel \
361> -f values.yaml \
362> --set api.token="$API_TOKEN" \
363> --set setup.force=true
364> ```
365>
366> Revoke the API key once the upgrade completes.
367
368> [tab] Docker Compose
369>
370> **1. Increment the token version**
371>
372> 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.
373>
374> **2. Create a Tunnels API key**
375>
376> Create a fresh Tunnels API key.
377>
378> **3. Re-run setup**
379>
380> Re-run setup, then restart cloudflared with the new token:
381>
382> ```bash theme={null}
383> read -rs API_TOKEN && export API_TOKEN
384> docker compose run --rm setup
385>
386> export TUNNEL_TOKEN=$(sudo cat data/tunnel-token)
387> docker compose up -d cloudflared
388> ```
389>
390> 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.
391391
392392### Renew the server certificate
393393
394394The 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.
395395
396**Helm**
397
398The 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.
399
400**Docker Compose**
401
402Run the renewal from the deployment directory. With `--renew-before=720h` the command does nothing while more than 30 days of validity remain, so it is safe to run on a schedule such as a daily cron entry.
403
404```bash theme={null}
405docker compose run --rm setup renew-cert --output=dir:/data --renew-before=720h
406```
396> [tab] Helm
397>
398> 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.
399
400> [tab] Docker Compose
401>
402> Run the renewal from the deployment directory. With `--renew-before=720h` the command does nothing while more than 30 days of validity remain, so it is safe to run on a schedule such as a daily cron entry.
403>
404> ```bash theme={null}
405> docker compose run --rm setup renew-cert --output=dir:/data --renew-before=720h
406> ```
407407
408408## Remove a tunnel
409409
410410
No line in this hunk matches that.