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à.
Ti serve:
tnl_...). Il provisioning manuale parte sempre da un tunnel creato nella Console.fdrl_...) e l'ID della tua organizzazione.openssl (1.1.1 o successivo).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 passaggi di installazione seguenti eseguono cd in mcp-tunnel/ e indicano dove aggiungere il servizio e la route corrispondenti.
Questa guida fornisce un approccio di riferimento che usa 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 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.
Prepara la directory di deployment
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 dell'accesso in scrittura a data/.
Scrivi docker-compose.yaml
Il file compose fissa le immagini tramite digest SHA-256, esegue ogni container come non-root con un filesystem di 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 in modo 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: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 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
EOFEffettua 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-000000000000Se la tua regola di federazione ha come ambito 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 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 ed emettere il token; l'audience della regola deve corrispondere all'audience che richiedi al momento dell'emissione del token.
Esegui il componente di setup:
docker compose run --rm setupsetup 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 tal 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 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 vita breve (1 ora per impostazione predefinita) e scadono automaticamente; non c'è nulla da revocare dopo il completamento del setup.
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
EOFLa route echo: punta al server MCP di esempio; sostituiscila con (o aggiungi) le tue route. Consulta il riferimento sulla configurazione del proxy per tutti i campi disponibili.
Avvia il 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, emetti 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 di effettuare la rotazione quando il valore
# non è cambiato.
# export TUNNEL_ID=tnl_... # imposta solo se l'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 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 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 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, poi aggiorna la variabile d'ambiente TUNNEL_TOKEN su ogni host e riavvia cloudflared (docker compose up -d cloudflared).
Fare clic su Rotate token invalida immediatamente il token corrente. Tra quel momento e l'aggiornamento di TUNNEL_TOKEN su ogni host con 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?