Distribuire i tunnel MCP con Docker Compose

Questa guida distribuisce lo stack del tunnel come container rafforzati su un singolo host. La stessa configurazione può essere replicata su più host per garantire la disponibilità.

Prima di iniziare

Hai bisogno di:

• Un tunnel creato nella Console. Segui Creare un tunnel e annota l'ID del tunnel (tnl_...).
• Un modo per l'host di autenticarsi all'API Tunnels.
  • Accesso programmatico (consigliato). Attiva Set up programmatic access durante la creazione del tunnel in modo che il componente di setup possa autenticarsi tramite Workload Identity Federation. Annota l'ID della regola di federazione (fdrl_...) e l'ID della tua organizzazione.
  • Manuale. Salta l'accesso programmatico. Dovrai ottenere il token del tunnel dalla Console, generare autonomamente una CA e un certificato server, e registrare la CA nella Console.
• Un host con Docker e Docker Compose installati. Il flusso manuale richiede anche openssl (1.1.1 o versione successiva).
• Connettività di rete in uscita dall'host verso api.anthropic.com (443 TCP) e il tunnel edge (7844 TCP e UDP). Consulta i requisiti di rete completi.
• Uno o più server MCP in esecuzione e raggiungibili dall'host agli indirizzi che configurerai sotto routes. Se non ne hai ancora uno, usa il server di esempio.

Opzionale: Usa un server MCP di esempio

Se non hai un server MCP disponibile per i test, usa questo server minimale:

mkdir -p mcp-tunnel
cat > mcp-tunnel/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

I seguenti passaggi di installazione eseguono cd in mcp-tunnel/ e indicano dove aggiungere il servizio e la route corrispondenti.

Installazione

Questa guida fornisce un approccio di riferimento utilizzando Docker Compose. Sei responsabile di adattarlo per soddisfare i requisiti di sicurezza della tua organizzazione.

Il file compose legge TUNNEL_TOKEN dall'ambiente dell'host senza alcun valore predefinito, quindi l'export deve essere ripetuto in ogni nuova shell e dopo un riavvio.

Per un deployment multi-VM, copia la directory mcp-tunnel/ su ciascun host, imposta TUNNEL_TOKEN ed esegui docker compose up -d. Nel flusso programmatico TUNNEL_TOKEN è $(sudo cat data/tunnel-token); nel flusso manuale è il valore che hai copiato dalla Console. Lo stesso token del tunnel e gli stessi certificati funzionano su tutte le repliche.

Verifica il deployment

Verifica end-to-end chiamando un server MCP upstream dal lato di Anthropic: consulta Usare i server MCP tramite tunnel. Con il server MCP di esempio, l'URL instradato è https://echo.<your-tunnel-domain>/mcp. Se la verifica fallisce, consulta Risoluzione dei problemi.

Aggiornamenti

Esegui i comandi in questa sezione dall'interno della directory di deployment mcp-tunnel/.

Ruotare il token del tunnel

Con l'accesso programmatico, incrementa --token-version nel comando del servizio setup, imposta gli identificatori di Workload Identity Federation, genera un nuovo JWT OIDC e riesegui il componente di setup:

# Modifica docker-compose.yaml: incrementa l'intero nell'argomento
# --token-version del servizio setup (ad esempio, da --token-version=1 a
# --token-version=2). Il binario di setup rifiuta la rotazione se il valore
# non è cambiato.

export TUNNEL_ID=tnl_...
export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...
export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
# export ANTHROPIC_WORKSPACE_ID=wrkspc_...   # se la regola è limitata al workspace
# Rigenera ANTHROPIC_IDENTITY_TOKEN seguendo la guida del provider WIF per il tuo
# ambiente (sarà scaduto dall'installazione).
export ANTHROPIC_IDENTITY_TOKEN=...

docker compose run --rm setup

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

L'argomento --token-version viene modificato in docker-compose.yaml anziché passato sulla riga di comando in modo che il nuovo valore persista per le esecuzioni future del componente di setup. Il componente di setup si autentica con Workload Identity Federation; non c'è alcun token API da revocare.

Senza accesso programmatico, fai clic su Rotate token nella pagina di dettaglio del tunnel nella Console, quindi aggiorna la variabile d'ambiente TUNNEL_TOKEN su ciascun host e riavvia cloudflared (docker compose up -d cloudflared).

Rinnovo del certificato

Sei responsabile del monitoraggio della scadenza e del rinnovo del certificato server prima che scada.

Con l'accesso programmatico:

docker compose run --rm setup renew-cert --output=dir:/data

Gli argomenti CLI sostituiscono il command del servizio setup (gli argomenti init) ma mantengono il suo entrypoint, quindi questo esegue /setup renew-cert --output=dir:/data.

Senza accesso programmatico, firma un nuovo certificato server con la tua CA esistente (la CA registrata nella Console non cambia) e sostituisci data/tls.crt. Imposta prima TUNNEL_DOMAIN se stai eseguendo questo da una nuova shell.

export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE
openssl req -new -key 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

In entrambi i flussi il proxy esegue il polling di tls.cert_file e lo ricarica automaticamente, quindi non è necessario alcun riavvio.

Passaggi successivi