Deploy MCP tunnels with Docker Compose

This path requires the host to have an OIDC identity provider (such as a cloud VM metadata server or SPIFFE). If it doesn't, use the Without programmatic access tab instead.

The setup component uses Workload Identity Federation to fetch the tunnel token, generate a CA and server certificate, and register the CA with Anthropic.

1. 1

   Prepare the deployment directory

   mkdir -p mcp-tunnel/{config,data}
   cd mcp-tunnel
   sudo chown 65532:65532 data

   

   The containers run as the non-root UID 65532 and need write access to data/.

2. 2

   Write docker-compose.yaml

   The compose file pins images by SHA-256 digest, runs every container as non-root with a read-only filesystem, drops all Linux capabilities, and disables privilege escalation.

   cat > docker-compose.yaml <<'EOF'
   services:
     setup:
       image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:efb27b299d627e4134815663cb8896641eeaee025d734c0f695582b4df38f013
       entrypoint: ["/setup"]
       command:
         - init
         - --api-url=https://api.anthropic.com
         - --output=dir:/data
         - --token-version=1
       environment:
         - TUNNEL_ID
         - ANTHROPIC_FEDERATION_RULE_ID
         - ANTHROPIC_ORGANIZATION_ID
         - ANTHROPIC_WORKSPACE_ID
         - ANTHROPIC_IDENTITY_TOKEN
       volumes:
         - ./data:/data
       user: "65532:65532"
       read_only: true
       security_opt:
         - no-new-privileges:true
       cap_drop:
         - ALL
       profiles: ["setup"]
   
     cloudflared:
       image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
       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:efb27b299d627e4134815663cb8896641eeaee025d734c0f695582b4df38f013
       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

   
3. 3

   Provision the tunnel

   Set the identifiers. Leave TUNNEL_ID unset to have the setup component create a tunnel; set it to attach to an existing tunnel from the Console:

   # export TUNNEL_ID=tnl_...   # set to attach to an existing tunnel
   export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...
   export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000

   

   If your federation rule is scoped to a workspace other than your organization's default, also set ANTHROPIC_WORKSPACE_ID=wrkspc_...; the setup component uses the default workspace otherwise. An auto-created tunnel is created in that workspace.

   Set ANTHROPIC_IDENTITY_TOKEN to an OIDC JWT from this host's identity provider. Follow the WIF guide for your provider to register the issuer, set the rule's subject, and mint the token; the rule's audience must match the audience you request when minting.

   Run the setup component:

   docker compose run --rm setup

   

   setup init is idempotent over data/: re-running it reuses the tunnel ID and CA already stored there and never creates a second tunnel. A new CA is generated and registered only when data/ is empty or TUNNEL_ID has changed; in that case the cap of two active certificates applies, so revoke one in the Console first if both slots are filled.

   See Setup component authentication failures if it errors.

   Retrieve your tunnel domain and export it for later steps:

   export TUNNEL_DOMAIN=$(sudo cat data/tunnel-domain)
   echo "$TUNNEL_DOMAIN"

   
4. 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
   shutdown_timeout: 30s
   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. 5

   Start the deployment

   export TUNNEL_TOKEN=$(sudo cat data/tunnel-token)
   docker compose up -d

   