Deploy MCP tunnels with Docker Compose

Use this flow if you didn't turn on Set up programmatic access, or for local development and testing. There is no setup service.

1. Get the tunnel token and domain from the Console

   On the tunnel detail page, copy the Domain (it has the form abcd1234.tunnel.anthropic.com), then click the eye icon next to Token to fetch the tunnel token and use the copy icon to copy it.

   Set both as shell variables for the rest of the guide:

   export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE
   export TUNNEL_TOKEN='eyJ...'
   

2. Scaffold and generate certificates

   mkdir -p mcp-tunnel/{data,config}
   cd mcp-tunnel
   

   The proxy listens on :8080 over plain WebSocket; the inner TLS handshake happens inside that WebSocket stream using these certificates. Anthropic verifies the inner handshake against the CA you register in the Console. The server certificate's SAN must include *.<tunnel-domain> per the certificate requirements.

   # Self-signed CA. Explicit extensions so it satisfies the certificate
   # requirements regardless of distro openssl.cnf defaults.
   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"
   
   # Extension file for the server certificate. Using -extfile (instead of
   # -copy_extensions, which is OpenSSL 3.0+ only) keeps this working on
   # OpenSSL 1.1.x.
   cat > data/tls.ext <<EOF
   subjectAltName = DNS:${TUNNEL_DOMAIN},DNS:*.${TUNNEL_DOMAIN}
   authorityKeyIdentifier = keyid,issuer
   extendedKeyUsage = serverAuth
   EOF
   
   # Server certificate signed by the CA
   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
   

3. Register the CA certificate in the Console

   On the tunnel detail page, scroll to the Certificates section and click Add certificate. Upload data/ca.crt directly with Choose file (the modal accepts .pem, .crt, and .cer), or paste its contents:

   cat data/ca.crt
   

   The tunnel's status flips to Active once a certificate is registered. See Add a CA certificate.

4. Write the proxy config

   tunnel_domain is required: the proxy uses it to strip the domain suffix from incoming hostnames before looking up the subdomain in routes. routes is a flat map from subdomain to upstream URL, not a list.

   cat > config/mcp-proxy.yaml <<EOF
   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
   EOF
   

   The echo: route targets the sample MCP server; replace it with (or add) your own routes. See the proxy configuration reference for all available fields.

5. Write docker-compose.yaml

   In this flow no ingress rules are configured server-side, so cloudflared needs an explicit local target. Share the proxy's network namespace and pass --url http://localhost:8080 so cloudflared forwards traffic to the proxy in the same netns; without it, requests reach cloudflared with no route and fail with a 503 (which surfaces to callers as a 500).

   cat > docker-compose.yaml <<'EOF'
   services:
     cloudflared:
       image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
       # --url is required: no ingress rules are pushed in the manual flow,
       # so without it cloudflared 503s every request.
       command: tunnel --no-autoupdate run --url http://localhost:8080
       environment:
         - TUNNEL_TOKEN
       # Share the proxy's netns so localhost:8080 reaches it.
       network_mode: "service:mcp-proxy"
       restart: unless-stopped
       user: "65532:65532"
       read_only: true
       security_opt:
         - no-new-privileges:true
       cap_drop:
         - ALL
       stop_grace_period: 30s
       logging:
         options:
           max-size: "10m"
           max-file: "3"
   
     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
       user: "65532:65532"
       read_only: true
       security_opt:
         - no-new-privileges:true
       cap_drop:
         - ALL
       stop_grace_period: 30s
       logging:
         options:
           max-size: "10m"
           max-file: "3"
   EOF
   

   If you're using the sample MCP server, append it as a service:

   cat >> docker-compose.yaml <<'EOF'
   
     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
   

6. Start the deployment

   docker compose up -d