claude-plugins-official/plugins/mcp-tunnels/commands/create-docker-mcp-tunnel.md

---
description: Stand up an Anthropic MCP tunnel locally with Docker Compose so Claude can call a private MCP server (manual-credentials quickstart).
argument-hint: "[deployment-dir] (default: ./mcp-tunnel)"
allowed-tools: [Bash, Read, Write, Edit, AskUserQuestion]
---

# Create a Docker MCP tunnel

Drive the
[**MCP tunnels quickstart**](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/quickstart)
end to end: from zero to Claude calling a private MCP server through an
Anthropic-operated tunnel, using Docker Compose with manually supplied
credentials (the shortest path for local testing).

> MCP tunnels is in **research preview**. It is provided "as-is" with no uptime
> or support commitment and depends on a third-party transport (Cloudflare).
> Do not put production traffic through this without reading the
> [security model](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/security).

You are guiding the user through a mix of **local commands you run** and
**Console actions only they can do** (creating the tunnel, uploading the CA).
Be a careful operator: explain each step briefly, run the commands, check the
output, and stop with a clear diagnosis if something fails.

Deployment directory: use `$ARGUMENTS` if the user passed a path, otherwise
default to `./mcp-tunnel`. Refer to it below as `$DIR`.

## What you'll build

A container stack on the user's machine:

- **mcp-proxy** — Anthropic's proxy. Terminates the inner TLS handshake using
  a certificate the user controls, validates upstream IPs, routes by hostname.
- **cloudflared** — the tunnel agent. Outbound-only connection to the Anthropic
  tunnel edge; shares the proxy's network namespace.
- **hello-mcp** *(optional)* — a sample FastMCP server, only if the user has no
  MCP server of their own to expose yet.

When it's up, the routed server is reachable from Claude at
`https://<subdomain>.<tunnel-domain>/<path>` with nothing listening on a public
port.

## Step 0 — Preflight

Run these and report what's missing before going further:

```bash
docker --version && docker compose version && openssl version
```

- Docker + Docker Compose are required. `openssl` 1.1.1+ is required (the
  commands below use `-addext`, available in 1.1.1+).
- Confirm the host has **outbound** access to `api.anthropic.com:443` and the
  tunnel edge (`198.41.192.0/19`, `2606:4700:a0::/44`) on **7844 TCP and UDP**.
  No inbound ports are opened.

If `docker compose` (v2) is unavailable but `docker-compose` (v1) exists, use
that and tell the user; the compose file is v2-compatible.

## Step 1 — Create the tunnel (Console — user action)

Tell the user to do this in the [Claude Console](https://console.anthropic.com)
(see [Create a tunnel](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#create-a-tunnel)):

1. Sidebar → **Manage → MCP tunnels** → **New tunnel**. Give it a name.
2. Leave **Set up programmatic access** **off** — this quickstart uses manual
   credentials.
3. Open the tunnel. From the **Connection** section copy two values:
   - **Domain** — looks like `abcd1234.tunnel.anthropic.com`
   - **Token** — click the eye icon, then copy

Then ask the user, via AskUserQuestion or a direct prompt, for the **Domain**.
**Do not ask them to paste the Token into the chat.** The token is a secret
that authenticates the outbound tunnel connection; keep it out of the
transcript. Instead, tell them you will create a `$DIR/.env` file and they
should paste the token into it themselves (Step 3), or have them export it:
`export TUNNEL_TOKEN='eyJ...'` in the shell you'll run compose from.

Record the domain as `TUNNEL_DOMAIN` for the steps below.

## Step 2 — Deployment directory

```bash
mkdir -p "$DIR"/{config,data}
cd "$DIR"
```

## Step 3 — Credentials file

Create `$DIR/.env` (compose auto-loads it; this survives reboots, unlike a
shell `export`). Write `TUNNEL_DOMAIN` yourself; leave a placeholder for the
secret and have the **user** fill it in:

```
TUNNEL_DOMAIN=<the domain from step 1>
TUNNEL_TOKEN=PASTE_TUNNEL_TOKEN_HERE
```

Then lock it down and make sure it never gets committed:

```bash
chmod 600 "$DIR/.env"
printf '.env\ndata/\n' > "$DIR/.gitignore"
```

Pause and have the user replace `PASTE_TUNNEL_TOKEN_HERE` with the real token
(tell them the exact file path). Verify it's set without printing it:

```bash
cd "$DIR" && grep -q '^TUNNEL_TOKEN=eyJ' .env && echo "token looks set" || echo "token NOT set — edit .env"
```

Load it for the openssl/config steps in this shell:

```bash
cd "$DIR" && set -a && . ./.env && set +a && echo "domain: $TUNNEL_DOMAIN"
```

## Step 4 — Generate the CA and server certificate

The proxy terminates an inner TLS handshake using a certificate signed by a CA
the user controls. Generate both (Linux/macOS shown; the
[quickstart](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/quickstart)
also has a Windows PowerShell variant — offer it if the user is on Windows):

```bash
cd "$DIR"

openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout data/ca.key -out data/ca.crt \
  -days 3650 -subj "/CN=mcp-tunnel-ca" \
  -addext "basicConstraints=critical,CA:TRUE" \
  -addext "keyUsage=critical,keyCertSign,cRLSign" \
  -addext "subjectKeyIdentifier=hash"

cat > data/tls.ext <<EOF
subjectAltName = DNS:${TUNNEL_DOMAIN},DNS:*.${TUNNEL_DOMAIN}
authorityKeyIdentifier = keyid,issuer
extendedKeyUsage = serverAuth
EOF

openssl req -newkey rsa:2048 -nodes \
  -keyout data/tls.key -out /tmp/server.csr \
  -subj "/CN=${TUNNEL_DOMAIN}"
openssl x509 -req -in /tmp/server.csr \
  -CA data/ca.crt -CAkey data/ca.key -CAcreateserial \
  -out data/tls.crt -days 90 -extfile data/tls.ext

chmod 644 data/tls.key
```

Why these flags: the explicit `-addext` extensions make the CA satisfy the
tunnel's [certificate requirements](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference#certificate-requirements)
regardless of distro `openssl.cnf` defaults;
`-extfile` (not `-copy_extensions`, which is OpenSSL 3.0+ only) keeps this
working on OpenSSL 1.1.x and adds the `AuthorityKeyIdentifier` the proxy
requires. `chmod 644 data/tls.key` is **required**: openssl writes the key
`0600` but the proxy container runs as a non-root user and must read it.

`data/tls.key` and `data/ca.key` are sensitive — they live under `data/`,
which the `.gitignore` from Step 3 already excludes.

## Step 5 — Register the CA (Console — user action)

Have the user, on the tunnel detail page, scroll to **Certificates** →
**Add certificate**
(see [Add a CA certificate](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate)),
and upload `$DIR/data/ca.crt` (or paste its contents —
print it with `cat data/ca.crt` so they can copy it). The tunnel status flips
to **Active** once a certificate is registered. The tunnel will not appear in
the agent picker until this is done.

Wait for the user to confirm the tunnel shows **Active** before continuing.

## Step 6 — Choose the upstream MCP server

Ask the user (AskUserQuestion):

- **"I have an MCP server already"** — get its reachable address as
  `scheme://host:port` (port mandatory, no path — the proxy rejects a path in
  the upstream value at config load). It must be reachable from the proxy
  container and resolve to an RFC1918 private address (`10/8`, `172.16/12`,
  `192.168/16`); the proxy refuses public/loopback upstreams by default
  (SSRF protection). If it runs as a Compose service, add it to the compose
  file so it shares the network. If it runs on the host, see Troubleshooting
  ("host process"). Pick a route subdomain with the user (e.g. `wiki`).
- **"Use the sample server"** — scaffold the FastMCP `hello-server` below as a
  Compose service `hello-mcp` and route subdomain `echo`.

### Sample server (only if chosen)

Write `$DIR/hello_server.py`:

```python
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("hello-server", host="0.0.0.0", port=9000)


@mcp.tool()
def hello(name: str = "world") -> str:
    """Say hello to someone."""
    return f"Hello, {name}!"


if __name__ == "__main__":
    mcp.run(transport="streamable-http")
```

## Step 7 — Proxy config

Write `$DIR/config/mcp-proxy.yaml`. `tunnel_domain` is **required** (the
proxy strips it from the incoming hostname to find the subdomain in `routes`).
`routes` is a **flat map** subdomain → upstream URL, *not* a list:

```yaml
listen_addr: ":8080"
log_level: info
tunnel_domain: <TUNNEL_DOMAIN>
tls:
  cert_file: /data/tls.crt
  key_file: /data/tls.key
routes:
  echo: http://hello-mcp:9000
```

Substitute the real `TUNNEL_DOMAIN`. Replace the `routes:` block with the
user's chosen subdomain → upstream if they brought their own server (e.g.
`wiki: http://wiki-mcp.internal:8080`). You can keep multiple routes.

## Step 8 — Compose file

Write `$DIR/docker-compose.yaml`. Images are pinned by digest:

```yaml
services:
  mcp-proxy:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:6b9adedbf2763143ec72f106ecaf0ce7fd3294e89b208f54a1db97a33d14c5ba
    command: ["-config", "/etc/mcp-proxy/config.yaml"]
    volumes:
      - ./config/mcp-proxy.yaml:/etc/mcp-proxy/config.yaml:ro
      - ./data:/data:ro
    restart: unless-stopped

  cloudflared:
    image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
    command: tunnel --no-autoupdate run --url http://localhost:8080
    environment:
      - TUNNEL_TOKEN
    network_mode: "service:mcp-proxy"
    restart: unless-stopped
```

`--url http://localhost:8080` is **required** in the manual flow: no ingress
rules are pushed server-side, so without it cloudflared 503s every request.
`network_mode: "service:mcp-proxy"` shares the proxy's netns so
`localhost:8080` reaches it. `environment: - TUNNEL_TOKEN` (no value) passes
the variable through from `.env`.

If the sample server was chosen, append the service:

```yaml
  hello-mcp:
    image: python:3.13-slim
    working_dir: /app
    volumes:
      - ./hello_server.py:/app/hello_server.py:ro
    command: sh -c "pip install --quiet mcp && python hello_server.py"
    restart: unless-stopped
```

If the user brought their own server *and* it's containerized, add its service
here too so it shares the Compose network with the proxy.

(For a hardened single-host deployment — non-root user, read-only rootfs,
`cap_drop: ALL`, `no-new-privileges` — point the user at
[Deploy with Docker Compose](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-compose);
this quickstart keeps it minimal for fast local testing.)

## Step 9 — Start and verify

```bash
cd "$DIR" && docker compose up -d
sleep 5
docker compose logs mcp-proxy | grep -i "route configured"
docker compose logs cloudflared | grep -i "Registered tunnel connection"
```

Expect one `route configured` line per route and **four**
`Registered tunnel connection` lines. Containers take a few seconds; rerun the
log greps if they come back empty (don't conclude failure on the first empty
result). If they stay empty, go to Troubleshooting.

## Step 10 — Call it from Claude

Tell the user both options:

**Managed Agents (Console):** **Managed Agents → Sessions** → new session →
agent picker **Create new agent** → **+ MCP Server** → select the tunnel →
**Subdomain** = the route (`echo`), **Path** = `mcp` (FastMCP
`streamable-http` serves at `/mcp`). Then ask: *"Use the hello tool to greet
tunnel."* — expect a tool call and its result.

**Messages API:** the host is `<subdomain>.<tunnel-domain>`; the path is
whatever the upstream serves (`/mcp` for FastMCP). Use an API key for the
workspace the tunnel was created in.

```bash
curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -d "{
    \"model\": \"claude-opus-4-7\",
    \"max_tokens\": 1024,
    \"mcp_servers\": [{\"type\": \"url\", \"name\": \"echo\", \"url\": \"https://echo.${TUNNEL_DOMAIN}/mcp\"}],
    \"tools\": [{\"type\": \"mcp_toolset\", \"mcp_server_name\": \"echo\"}],
    \"messages\": [{\"role\": \"user\", \"content\": \"call hello with name=tunnel\"}]
  }"
```

The tunnel carries encrypted traffic but does **not** authenticate to the
upstream. If the upstream MCP server requires its own auth, the user supplies
it the same as for any other MCP server.

## Troubleshooting (diagnose in this order)

| Symptom | Cause | Fix |
|---|---|---|
| Caller sees HTTP 500; cloudflared logs `No ingress rules were defined` | cloudflared has no local target | Ensure `--url http://localhost:8080` and `network_mode: "service:mcp-proxy"` are both present, then `docker compose up -d` |
| Proxy exits `cannot unmarshal !!seq into map[string]string` | `routes` written as a YAML list | Use `routes: { name: http://host:port }`, not a list of objects |
| Proxy exits `open /data/tls.key: permission denied` | key is `0600`, proxy runs non-root | `chmod 644 data/tls.key` |
| Proxy logs `no route for host` (caller gets `502 No route configured for host`) | `tunnel_domain` missing or wrong | Set it to the exact domain on the tunnel detail page; then **restart the proxy** (next row) |
| Edited config but nothing changed | proxy does **not** hot-reload `config.yaml` (only `tls.cert_file`) | `docker compose restart mcp-proxy` — `up -d` alone won't recreate it on a file-content change |
| `tls handshake failed ... unknown certificate authority` | CA not registered/revoked on this tunnel | Re-upload `data/ca.crt` in the Console (Step 5) |
| `tls handshake failed ... bad certificate` | server cert SAN ≠ `*.<tunnel-domain>`, or expired | Regenerate the server cert (Step 4) with the correct `TUNNEL_DOMAIN` |
| `IP validation failed: <ip> is not a private address` | upstream resolves outside RFC1918 (e.g. `127.0.0.1`, public IP) | Run the upstream as a Compose service on the proxy's network; or narrow `upstream.allowed_ips` deliberately (avoid `0.0.0.0/0` outside local testing) |
| `dial tcp ...: connect: connection refused` for `host.docker.internal` | rootless Docker can't reach the host netns | Run the MCP server as a Compose service instead of a host process |
| HTTP 502, no `request started` in proxy log | cloudflared hadn't finished registering, or rolling update | Wait for ×4 `Registered tunnel connection` and retry |
| Tunnel missing from agent **+ MCP Server** picker | no active certificate, or wrong workspace | Register a CA cert (Step 5); open the session in the tunnel's workspace |
| `curl https://<proxy>:8080` fails `wrong version number` | expected — listener is plaintext WS, TLS is inside the WS stream | Don't curl the proxy directly; verify via Managed Agent or Messages API |

`docker compose logs cloudflared` (token/edge reachability) and
`docker compose logs mcp-proxy` (config/cert/routing) are the two primary
diagnostics. Check the outbound connection first, then the inner TLS handshake,
then upstream routing. See
[Troubleshooting](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting)
for additional cases.

## Operational notes (mention briefly, don't run unprompted)

- **Token rotation:** Console → **Rotate token** invalidates the old token
  immediately. Update `TUNNEL_TOKEN` in `.env` and
  `docker compose up -d cloudflared`.
- **Cert renewal:** the server cert is valid 90 days. Re-sign with the same CA
  (the registered CA doesn't change) and replace `data/tls.crt`; the proxy
  polls and reloads it, no restart needed.
- **Config changes always need** `docker compose restart mcp-proxy`.

## Wrap up

Summarize: deployment dir, route(s) configured, tunnel domain, and the exact
URL Claude reaches the server at. Remind the user the token is a live secret in
`$DIR/.env` (chmod 600, gitignored) and that this is a research-preview,
local-testing setup — point them at
[Deploy with Docker Compose](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-compose) /
[Deploy with Helm](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm)
for a hardened or programmatic-access deployment.