I tunnel MCP sono in anteprima di ricerca. Richiedi l'accesso per provarli.
Questa guida distribuisce lo stack di tunnel come container rafforzati su un singolo host. La stessa configurazione può essere replicata su più host per garantire la disponibilità.
Hai bisogno di:
tnl_...). Il provisioning manuale parte sempre da un tunnel creato nella Console.fdrl_...) e l'ID della tua organizzazione.openssl (1.1.1 o più recente).api.anthropic.com (443 TCP) e il tunnel edge (7844 TCP e UDP). Consulta i requisiti di rete completi.routes. Se non ne hai ancora uno, usa il server 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")
EOFI seguenti passaggi di installazione eseguono cd in mcp-tunnel/ e indicano dove aggiungere il servizio e la route corrispondenti.
Questa guida fornisce un approccio di riferimento utilizzando Docker Compose. Sei responsabile di adattarlo per soddisfare i requisiti di sicurezza della tua organizzazione.
Questo percorso richiede che l'host disponga di un provider di identità OIDC (come un server di metadati di una VM cloud o SPIFFE). In caso contrario, usa invece la scheda Without programmatic access.
Il componente di setup utilizza Workload Identity Federation per recuperare il token del tunnel, generare una CA e un certificato server, e registrare la CA presso Anthropic.
Prepare the deployment directory
mkdir -p mcp-tunnel/{config,data}
cd mcp-tunnel
sudo chown 65532:65532 dataI container vengono eseguiti con l'UID non-root 65532 e necessitano di accesso in scrittura a data/.
Write 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:9d4c80593b559fc3ca3814866418744fa94858b02a4d4a4cc52d423e732ccc81
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ì localhost:8080 lo raggiunge.
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:9d4c80593b559fc3ca3814866418744fa94858b02a4d4a4cc52d423e732ccc81
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"
EOFSe stai utilizzando 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
EOFProvision the tunnel
Imposta gli identificatori. Lascia TUNNEL_ID non impostato per far sì che il componente di setup crei un tunnel; 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-000000000000Se 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 utilizza il workspace predefinito. Un tunnel creato automaticamente viene creato in quel workspace.
Imposta ANTHROPIC_IDENTITY_TOKEN su un JWT OIDC proveniente dal provider di identità di questo host. Segui la guida WIF per il tuo provider per registrare l'issuer, impostare il subject della regola e generare il token; l'audience della regola deve corrispondere all'audience che richiedi durante la generazione.
Esegui il componente di setup:
docker compose run --rm setupsetup init è idempotente su 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 tal caso si applica il limite di due certificati attivi, quindi revocane uno nella Console prima se entrambi gli slot sono occupati.
Consulta Errori di autenticazione del componente di setup se si verifica un errore.
Recupera il dominio del tuo tunnel ed esportalo per i passaggi successivi:
export TUNNEL_DOMAIN=$(sudo cat data/tunnel-domain)
echo "$TUNNEL_DOMAIN"I token di Workload Identity Federation hanno una durata breve (un'ora per impostazione predefinita) e scadono automaticamente; non c'è nulla da revocare dopo il completamento del setup.
Write the proxy config
tunnel_domain è obbligatorio: il proxy lo utilizza per rimuovere il suffisso del 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
EOFLa 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.
Start the deployment
export TUNNEL_TOKEN=$(sudo cat data/tunnel-token)
docker compose up -dIl 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 su più VM, copia la directory mcp-tunnel/ su ogni 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 end-to-end chiamando un server MCP upstream dal lato di Anthropic: consulta Usa i server MCP attraverso il tunnel. Con il server MCP di esempio, l'URL instradato è https://echo.<your-tunnel-domain>/mcp. Se la verifica fallisce, consulta Risoluzione dei problemi.
Esegui i comandi di questa sezione dall'interno della directory di deployment mcp-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_... # impostalo solo se lo hai impostato durante l'installazione
export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...
export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
# export ANTHROPIC_WORKSPACE_ID=wrkspc_... # se la tua regola è limitata al workspace
# Rigenera ANTHROPIC_IDENTITY_TOKEN secondo la guida del provider WIF per il tuo
# ambiente (sarà scaduto dopo l'installazione).
export ANTHROPIC_IDENTITY_TOKEN=...
docker compose run --rm setup
export TUNNEL_TOKEN=$(sudo cat data/tunnel-token)
docker compose up -d cloudflaredL'argomento --token-version viene modificato in docker-compose.yaml anziché passato sulla riga di comando, in modo che il nuovo valore persista per le future esecuzioni del componente di setup. Il componente di setup si autentica con Workload Identity Federation; non c'è alcun token API da revocare.
Senza accesso programmatico, clicca su Rotate token nella pagina di dettaglio del tunnel nella Console, poi aggiorna la variabile d'ambiente TUNNEL_TOKEN su ogni host e riavvia cloudflared (docker compose up -d cloudflared).
Cliccare su Rotate token invalida immediatamente il token corrente. Tra quel momento e l'aggiornamento di TUNNEL_TOKEN su ogni host e il riavvio di cloudflared, qualsiasi host il cui cloudflared si riavvia (crash, riavvio dell'host) non può riconnettersi. Aggiorna tempestivamente ogni host dopo la rotazione.
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:/dataGli argomenti della CLI sostituiscono il command del servizio setup (gli argomenti di init) ma ne mantengono l'entrypoint, quindi questo esegue /setup renew-cert --output=dir:/data.
Passa --renew-before=720h per rendere il comando un no-op quando rimangono più di 30 giorni di validità. Questo lo rende sicuro da eseguire su una pianificazione fissa.
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 lo stai eseguendo 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.extIn entrambi i flussi il proxy esegue il polling di tls.cert_file e lo ricarica automaticamente, quindi non è necessario alcun riavvio.
Collega un server MCP upstream a un Managed Agent o all'API Messages.
Linee guida per il rafforzamento, rotazione delle credenziali e risposta alle violazioni.
Diagnostica problemi di connettività, TLS e routing.
Was this page helpful?