MCP tunnels quickstart

Connect Claude to a private MCP server using a local Docker Compose deployment.

Note

MCP tunnels is a research preview feature. Request access to try it.

This quickstart takes you from zero to Claude calling a private MCP server through a tunnel. It uses Docker Compose with manually supplied credentials, which is the shortest path for local testing. For production deployments, see Deploy with Helm or Deploy with Docker Compose.

What you'll build

A three-container stack on your machine: a sample MCP server, the tunnel proxy, and the outbound connector. When it's running, the sample server is reachable from Claude at https://echo.<your-tunnel-domain>/mcp even though nothing is listening on a public port.

What you need

Docker and Docker Compose on a machine with outbound internet access.
A role in the Claude Console that can manage MCP tunnels. See the Console guide prerequisites.
OpenSSL 1.1.1 or later. Preinstalled on macOS and most Linux distributions; on Windows, install it separately (the openssl binary must be on your PATH).

Create a tunnel
In the Claude Console sidebar, go to Manage > MCP tunnels and click New tunnel. Give it a name. Leave Set up programmatic access off; this quickstart uses manually supplied credentials.
After it's created, open the tunnel. Copy two values from the Connection section:
- Domain (looks like abcd1234.tunnel.anthropic.com)
- Token (click the eye icon, then copy)

Set up the deployment directory

mkdir -p mcp-tunnel/{config,data}
cd mcp-tunnel
export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE   # from step 1
export TUNNEL_TOKEN='eyJ...'            # from step 1

New-Item -ItemType Directory -Force -Path mcp-tunnel/config, mcp-tunnel/data | Out-Null
Set-Location mcp-tunnel
$env:TUNNEL_DOMAIN = "YOUR_TUNNEL_DOMAIN_HERE"   # from step 1
$env:TUNNEL_TOKEN  = "eyJ..."             # from step 1

Generate a CA and server certificate

The proxy terminates an inner TLS handshake using a certificate signed by a CA you control. Generate both:

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

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"

@"
subjectAltName = DNS:$env:TUNNEL_DOMAIN,DNS:*.$env:TUNNEL_DOMAIN
authorityKeyIdentifier = keyid,issuer
extendedKeyUsage = serverAuth
"@ | Set-Content -NoNewline -Encoding ascii -Path data/tls.ext

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

Back in the Console, on the tunnel detail page, click Add certificate and upload data/ca.crt (or paste its contents). The tunnel status flips to Active.

Write the sample MCP server

cat > hello_server.py <<'EOF'
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")
EOF

@'
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")
'@ | Set-Content -NoNewline -Encoding ascii -Path hello_server.py

Write the proxy config and compose file

cat > config/mcp-proxy.yaml <<EOF
listen_addr: ":8080"
tunnel_domain: ${TUNNEL_DOMAIN}
tls:
  cert_file: /data/tls.crt
  key_file: /data/tls.key
routes:
  echo: http://hello-mcp:9000
EOF

cat > docker-compose.yaml <<'EOF'
services:
  mcp-proxy:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:6b9adedbf2763143ec72f106ecaf0ce7fd3294e89b208f54a1db97a33d14c5ba
    volumes:
      - ./config/mcp-proxy.yaml:/etc/mcp-gateway/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

  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
EOF

@"
listen_addr: ":8080"
tunnel_domain: $env:TUNNEL_DOMAIN
tls:
  cert_file: /data/tls.crt
  key_file: /data/tls.key
routes:
  echo: http://hello-mcp:9000
"@ | Set-Content -NoNewline -Encoding ascii -Path config/mcp-proxy.yaml

@'
services:
  mcp-proxy:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:6b9adedbf2763143ec72f106ecaf0ce7fd3294e89b208f54a1db97a33d14c5ba
    volumes:
      - ./config/mcp-proxy.yaml:/etc/mcp-gateway/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

  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
'@ | Set-Content -NoNewline -Encoding ascii -Path docker-compose.yaml

Start it

docker compose up -d
docker compose logs mcp-proxy | grep "route configured"
docker compose logs cloudflared | grep "Registered tunnel connection"

docker compose up -d
docker compose logs mcp-proxy | Select-String "route configured"
docker compose logs cloudflared | Select-String "Registered tunnel connection"

You should see one route configured line for echo and four Registered tunnel connection lines. The containers take a few seconds to start; rerun the log commands if they come back empty.

Call it from Claude
In the Console, go to Managed Agents > Sessions and create a session. In the agent picker choose Create new agent, then click + MCP Server, select your tunnel, set Subdomain to echo and Path to mcp. Then ask:

Use the hello tool to greet tunnel.

You should see a tool call followed by its result.

Next steps

The tunnel is verified end to end. For production deployments:

◆Deploy with Docker Compose

Hardened single-host deployment, with or without programmatic access.

◆Deploy with Helm

Kubernetes deployment with automatic credential management.

MCP tunnels quickstart

What you'll build

What you need

Create a tunnel

Set up the deployment directory

Generate a CA and server certificate

Write the sample MCP server

Write the proxy config and compose file

Start it

Call it from Claude

Next steps