Distribuire i tunnel MCP con Docker Compose

Questo percorso richiede che l'host disponga di un identity provider OIDC (come il metadata server di una VM cloud o SPIFFE). In caso contrario, usa invece la scheda Senza accesso programmatico.

Il componente di setup usa Workload Identity Federation per recuperare il token del tunnel, generare una CA e un certificato server, e registrare la CA presso Anthropic.

1. 1

   Prepara la directory di distribuzione

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

   

   I container vengono eseguiti con l'UID non-root 65532 e necessitano dell'accesso in scrittura a data/.

2. 2

   Scrivi docker-compose.yaml

   Il file compose fissa le immagini tramite digest SHA-256, esegue ogni container come non-root con un filesystem in sola lettura, rimuove tutte le capability Linux e disabilita l'escalation dei privilegi.

   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
       # Condividi il netns del proxy così che localhost:8080 lo raggiunga.
       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

   

   Se stai usando il server MCP di esempio, aggiungilo come servizio:

   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

   Esegui il provisioning del tunnel

   Imposta gli identificatori. Lascia TUNNEL_ID non impostato per far creare un tunnel al componente di setup; impostalo per collegarti a un tunnel esistente dalla Console:

   # export TUNNEL_ID=tnl_...   # imposta per collegarti a un tunnel esistente
   export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...
   export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000

   

   Se la tua regola di federazione è limitata a un workspace diverso da quello predefinito della tua organizzazione, imposta anche ANTHROPIC_WORKSPACE_ID=wrkspc_...; altrimenti il componente di setup usa il workspace predefinito. Un tunnel creato automaticamente viene creato in quel workspace.

   Imposta ANTHROPIC_IDENTITY_TOKEN su un JWT OIDC emesso dall'identity provider di questo host. Segui la guida WIF per il tuo provider per registrare l'issuer, impostare il subject della regola ed emettere il token; l'audience della regola deve corrispondere all'audience che richiedi al momento dell'emissione.

   Esegui il componente di setup:

   docker compose run --rm setup

   

   setup init è idempotente rispetto a data/: rieseguirlo riutilizza l'ID del tunnel e la CA già memorizzati lì e non crea mai un secondo tunnel. Una nuova CA viene generata e registrata solo quando data/ è vuota o TUNNEL_ID è cambiato; in quel caso si applica il limite di due certificati attivi, quindi revocane prima uno nella Console se entrambi gli slot sono occupati.

   Consulta Errori di autenticazione del componente di setup in caso di errore.

   Recupera il dominio del tuo tunnel ed esportalo per i passaggi successivi:

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

   
4. 4

   Scrivi la configurazione del proxy

   tunnel_domain è obbligatorio: il proxy lo usa per rimuovere il suffisso di dominio dagli hostname in ingresso prima di cercare il sottodominio in routes. routes è una mappa piatta da sottodominio a URL upstream, non una lista.

   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

   

   La route echo: punta al server MCP di esempio; sostituiscila con (o aggiungi) le tue route. Consulta il riferimento alla configurazione del proxy per tutti i campi disponibili.

5. 5

   Avvia la distribuzione

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

   