Vai al contenuto principale

MCP Tunnels

Che cos'è?

Connetti Claude in modo sicuro ai server MCP in esecuzione nella tua rete privata senza aprire porte in ingresso o esporre servizi a Internet. MCP Tunnels è attualmente in beta privata e si basa sul servizio Tunnel di Cloudflare.

Come funziona

MCP Tunnels crea una connessione tra Claude e i tuoi server MCP interni crittografata in transito con più livelli di sicurezza.

Quando Claude ha bisogno di raggiungere un server MCP nella tua rete privata, la richiesta viaggia attraverso un tunnel sicuro. Distribuisci due componenti dalla tua parte:

  • cloudflared (agente tunnel di Cloudflare)

  • MCP Gateway (fornito da Anthropic)

Cloudflared avvia una connessione solo in uscita verso il perimetro di Cloudflare. Non è necessario aprire porte in ingresso nel tuo firewall. MCP Gateway termina un livello TLS interno, convalida gli IP upstream per prevenire SSRF e instrada ogni richiesta al server MCP corretto in base al sottodominio.

La connessione è protetta da tre livelli indipendenti: mTLS esterno tra Anthropic e Cloudflare (con convalida IP), TLS interno che crittografa i payload end-to-end dal backend di Anthropic al tuo gateway (progettato in modo che Cloudflare non abbia accesso ai payload MCP) e autenticazione OAuth a livello di applicazione su ogni server MCP.

Cosa distribuisci

cloudflared

Agente tunnel di Cloudflare. Avvia connessioni solo in uscita — non sono necessarie porte in ingresso.

MCP Gateway

Componente fornito da Anthropic che termina TLS interno, convalida gli IP e instrada le richieste ai tuoi server MCP.

Proprietà di sicurezza chiave

  • Nessuna porta in ingresso richiesta. cloudflared avvia solo connessioni in uscita — il tuo firewall rimane chiuso.

  • Crittografia end-to-end. Il traffico è crittografato in transito dal backend di Anthropic al tuo gateway. I payload MCP non possono essere letti da Cloudflare.

  • Difesa in profondità. Più livelli di autenticazione: mTLS, TLS interno e OAuth a livello di applicazione.

  • Protezione SSRF. Il gateway convalida gli IP upstream per aiutare a prevenire attacchi di falsificazione delle richieste.

Questa guida fornisce distribuzioni di riferimento tramite Helm (per Kubernetes) e Docker Compose. Sei responsabile dell'adattamento alle esigenze di sicurezza della tua organizzazione.

Responsabilità condivisa

Mantenere questo sistema sicuro è una responsabilità condivisa tra Anthropic e la tua organizzazione.

Anthropic è responsabile di:

  • Garantire che solo Anthropic possa accedere ai tunnel

  • Convalidare il tuo certificato CA prima di connettersi al tuo gateway

  • Garantire che Claude invii richieste solo ai tunnel di proprietà della tua organizzazione

Sei responsabile di:

  • Seguire le indicazioni in questo documento e qualsiasi indicazione successiva

  • Proteggere il token del tunnel e le chiavi private TLS

  • Configurare i tuoi server MCP per utilizzare l'autenticazione OAuth come descritto nella specifica MCP

  • Limitare l'accesso ai tuoi host gateway e ai server MCP al personale appropriato

  • Notificare Anthropic se sospetti che il sistema sia stato compromesso (vedi Rispondere a una violazione sospetta)

⚠️ Rischio di credenziali. Se un utente malintenzionato ottiene il tuo token del tunnel e una delle tue chiavi private TLS, potrebbe impersonare il tuo gateway e leggere i payload delle richieste MCP, inclusi i token OAuth. Proteggi queste credenziali secondo i requisiti di sicurezza della tua organizzazione, incluse le autorizzazioni dei file, la crittografia a riposo e la gestione dei segreti.

Prerequisiti

  • Una destinazione di distribuzione — un cluster Kubernetes (per Helm) o una VM con Docker e Docker Compose.

  • Un token API Anthropic per l'API Tunnels — generane uno da claude.ai → Organization Settings → Connectors → Tunnels API. La configurazione utilizza questo token per eseguire il provisioning del tunnel e registrare il tuo certificato CA. Il gateway non ne ha bisogno in fase di esecuzione. Revocalo una volta completata la configurazione.

  • Accesso di rete — connettività in uscita secondo la tabella sottostante.

  • Server MCP — uno o più server MCP in esecuzione nella tua rete privata che il gateway può raggiungere.

Requisiti di rete

Componente

Destinazione

Scopo

Configurazione (una tantum)

api.anthropic.com:443

(porta 443)

Provisioning del tunnel

cloudflared

Perimetro Cloudflare, porta 7844 TCP/UDP (198.41.192.0/19, 2606:4700:a0::/44)

Connessione tunnel

MCP Gateway

I tuoi server MCP

Traffico upstream

Consulta la documentazione del firewall tunnel di Cloudflare per l'elenco IP autorevole. Gli utenti Helm possono applicare questa restrizione di uscita abilitando il valore networkPolicy del grafico.

Scegli il tuo metodo di distribuzione

I tunnel MCP possono essere distribuiti tramite Helm (Kubernetes) o Docker Compose. Scegli il metodo più adatto alla tua infrastruttura.

⎈ Helm / Kubernetes

Consigliato per la maggior parte dei clienti. Automatizza il provisioning del tunnel e il rinnovo dei certificati. Archivia le credenziali come Secrets.

🐳 Docker Compose

Per distribuzioni su singolo host o VM.

Distribuzione Helm / Kubernetes

1. Scarica i valori del grafico

Scarica il file dei valori predefiniti. Include commenti che spiegano ogni campo.

Shell

helm show values \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 > values.yaml

2. Configura i tuoi percorsi

Modifica values.yaml e aggiungi almeno un percorso sotto gateway.config.routes. Ogni percorso mappa un prefisso di sottodominio a un URL server MCP upstream.

3. Rivedi i manifesti renderizzati

Renderizza il grafico con un token segnaposto per ispezionare le risorse Kubernetes prima dell'installazione. Il grafico richiede api.token per il rendering, ma helm template non chiama l'API.

Shell

helm template mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 \
  -n mcp-tunnel \
  -f values.yaml \
  --set api.token=placeholder > rendered.yaml

Rivedi rendered.yaml secondo le pratiche della tua organizzazione per la verifica dei manifesti di terze parti.

4. Installa il grafico

Archivia il tuo token API in una variabile di ambiente, quindi installa. È consigliato uno spazio dei nomi dedicato per l'isolamento.

Shell

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

helm install mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 \
  --namespace mcp-tunnel --create-namespace \
  -f values.yaml \
  --set api.token="$API_TOKEN"

⚠️ Importante: Revoca il token API al termine dell'installazione. Il passaggio del token tramite --set lo mantiene fuori dal tuo file dei valori, ma Helm lo registra comunque nella cronologia delle versioni (sh.helm.release.v1.* Secrets). I Kubernetes Secrets non sono crittografati a riposo per impostazione predefinita, quindi il token rimane recuperabile dal cluster fino a quando non lo revochi.

5. Recupera il dominio del tuo tunnel

Il Job di configurazione scrive il dominio del tunnel in un Secret. Avrai bisogno di questo per configurare i server MCP in Claude.

Shell

kubectl get secret mcp-tunnel -n mcp-tunnel \
  -o jsonpath='{.data.tunnel-domain}' | base64 -d

Una volta che il tunnel è attivo e in esecuzione, connettiti a Claude.

Facoltativo: Abilita NetworkPolicy

Imposta networkPolicy.enabled: true nel tuo file dei valori per limitare l'uscita del pod tunnel a livello di rete. Configura networkPolicy.mcpServers con selettori di etichette pod o intervalli CIDR per i tuoi server MCP upstream. La policy include già regole di uscita per cloudflared per raggiungere l'edge di Cloudflare. Il CNI del tuo cluster deve supportare NetworkPolicy—consulta il file dei valori per un esempio.

Facoltativo: Configurazione del gateway

I campi sotto gateway.config.* vengono passati al file di configurazione del gateway. Consulta Appendice: Configurazione del gateway per l'elenco completo. Gli aggiustamenti comuni includono upstream.allowed_ips, log_level e upstream.tls per percorsi https://. Per montare file aggiuntivi a cui fa riferimento la configurazione (come un bundle CA per upstream.tls.ca_file), utilizza gateway.extraVolumes e gateway.extraVolumeMounts.

Aggiornamenti

Specifica sempre --version su helm upgrade. Senza di esso, Helm estrae la versione più recente del grafico dal registro, che potrebbe non essere quella che hai revisionato.

Per modifiche di configurazione (percorsi, repliche, NetworkPolicy, ecc.), non è necessario alcun token API. Il Job di configurazione viene saltato negli aggiornamenti a meno che tu non passi api.token:

Shell

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 \
  -n mcp-tunnel \
  -f values.yaml

Per la rotazione del token del tunnel, incrementa tunnel.tokenVersion nel tuo file dei valori, genera un nuovo token API e aggiorna:

Shell

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 \
  -n mcp-tunnel \
  -f values.yaml \
  --set api.token="$API_TOKEN"

Revoca il token API al termine dell'aggiornamento.

Mantieni un file dei valori completo piuttosto che affidarti a --reuse-values. Helm unisce in profondità i campi della mappa, quindi l'eliminazione di un percorso con --reuse-values fallisce silenziosamente.

Utilizzo di helm template con kubectl o kustomize

Se preferisci renderizzare i manifesti e applicarli tu stesso (tramite kubectl apply o overlay kustomize), utilizza la modalità esterna (setup.enabled: false). Provisiona il tunnel separatamente (consulta Appendice: API Tunnels) e fornisci le credenziali come Secrets pre-creati a cui fanno riferimento external.tunnelTokenSecretName e external.serverCertSecretName. Se emetti i tuoi certificati invece di utilizzare il binario di configurazione, consulta Appendice: Requisiti dei certificati.

Distribuzione Docker Compose

1. Prepara la directory di distribuzione

Shell

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

Il chown consente al contenitore (che viene eseguito come UID 65532) di scrivere nella directory montata in bind.

2. Crea docker-compose.yaml

YAML

services:
  # One-time provisioning. Run with: docker compose run --rm setup
  setup:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-gateway@sha256:62ddf0897778c80997ca789189a8a0bd63df241659d661ff9d5b0e06b5ee1dcd
    entrypoint: ["/setup"]
    command:
      - init
      - --api-url=https://api.anthropic.com
      - --output=dir:/data
      - --token-version=1
    environment:
      - API_TOKEN
    volumes:
      - ./tunnel-data:/data
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    profiles: ["setup"]

  cloudflared:
    # Verify digest at https://hub.docker.com/r/cloudflare/cloudflared/tags
    image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
    command: tunnel --no-autoupdate --config /etc/cloudflared/config.yaml run
    environment:
      - TUNNEL_TOKEN
    volumes:
      - ./config/cloudflared-config.yaml:/etc/cloudflared/config.yaml: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"

  mcp-gateway:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-gateway@sha256:62ddf0897778c80997ca789189a8a0bd63df241659d661ff9d5b0e06b5ee1dcd
    volumes:
      - ./config/mcp-gateway.yaml:/etc/mcp-gateway/config.yaml:ro
      - ./tunnel-data:/data:ro
    restart: unless-stopped
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    # Should match shutdown_timeout in mcp-gateway config
    stop_grace_period: 30s
    logging:
      options:
        max-size: "10m"
        max-file: "3"

Misure di sicurezza: esecuzione non-root (UID 65532), filesystem di sola lettura, nessuna escalation di privilegi, tutte le capacità Linux eliminate, pinning dell'immagine tramite digest SHA256.

3. Provisioning del tunnel

Shell

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

docker compose run --rm setup

Il comando di configurazione crea un tunnel tramite l'API Tunnels, genera un certificato CA e server, registra il CA con Anthropic e scrive tutti gli output in ./tunnel-data/.

Recupera il dominio del tunnel per il passaggio successivo:

Shell

sudo cat tunnel-data/tunnel-domain

⚠️ Importante: revoca il token API prima di procedere.

4. Configurazione del gateway

Crea config/mcp-gateway.yaml:

YAML

listen_addr: ":8080"
log_level: info
shutdown_timeout: 30s

# Your tunnel domain from Step 3
tunnel_domain: abcd1234.tunnel.anthropic.com

tls:
  cert_file: /data/tls.crt
  key_file: /data/tls.key

routes:
  # Replace with your actual MCP servers.
  # With tunnel_domain set, keys are subdomain prefixes.
  docs: http://docs-mcp.internal:8080
  search: http://search-mcp.internal:8080

upstream:
  allowed_ips:
    - 10.0.0.0/8

Consulta Appendice: Configurazione del gateway per tutti i campi disponibili.

Crea config/cloudflared-config.yaml:

YAML

ingress:
  - service: http://mcp-gateway:8080

5. Distribuzione

Shell

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

Struttura della directory:

mcp-gateway/
├── docker-compose.yaml
├── config/
│   ├── cloudflared-config.yaml
│   └── mcp-gateway.yaml
└── tunnel-data/
    ├── tunnel-id
    ├── tunnel-domain
    ├── tunnel-token
    ├── token-version
    ├── ca.crt
    ├── ca.key
    ├── tls.crt
    └── tls.key

Considera di spostare la chiave privata CA e il token del tunnel in un archivio sicuro.

Per distribuzioni multi-VM: copia la directory mcp-gateway/ su ogni host. Lo stesso token del tunnel e i certificati funzionano su tutte le repliche.

Una volta che il tunnel è attivo e in esecuzione, connettiti a Claude.

Rinnovo del certificato (Compose)

Il certificato del server ha una validità di 90 giorni. Rinnova prima della scadenza:

Shell

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

Il gateway controlla il file del certificato ogni 30 secondi e lo ricarica automaticamente quando cambia. Consulta Appendice: Riferimento CLI di configurazione per i flag che rendono questo comando sicuro da eseguire in una pianificazione.

Rotazione del token del tunnel (Compose)

Modifica docker-compose.yaml per incrementare --token-version, quindi esegui di nuovo la configurazione con un token API nuovo:

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

docker compose run --rm setup

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

Revoca il token API una volta completata la rotazione.

Connettiti a Claude

Una volta che il tunnel è in esecuzione, registra i tuoi server MCP in Claude in modo che siano disponibili agli utenti.

1. Aggiungi server MCP

Un amministratore dell'organizzazione accede a Impostazioni organizzazione → Connettori → Aggiungi → Personalizzato → Web in claude.ai.

Inserisci ogni server MCP utilizzando il suo nome host del tunnel. Ad esempio, docs.abcd1234.tunnel.anthropic.com. Il prefisso del sottodominio corrisponde alla chiave di route dalla configurazione del gateway.

2. Gli utenti si connettono

I singoli utenti accedono a Impostazioni → Connettori e fanno clic su Connetti per ogni server MCP che desiderano utilizzare.

Aggiungere altri server in seguito? Aggiungi una nuova route alla tua configurazione, applica la modifica (helm upgrade o docker compose restart mcp-gateway) e registra il nuovo nome host in Claude. Non sono necessarie modifiche al certificato o a cloudflared. Il certificato wildcard copre tutti i sottodomini.

Procedure consigliate per la sicurezza

  1. Richiedi OAuth sui tuoi server MCP. Il tunnel e i livelli TLS proteggono il trasporto, ma se questi vengono mai compromessi, OAuth a livello di applicazione impedisce comunque l'invocazione di strumenti non autorizzati. Configura ogni server MCP per richiedere l'autenticazione OAuth come descritto nella specifica MCP.

  2. Abilita SSO per la tua organizzazione claude.ai. I token del tunnel vengono generati dalla console claude.ai. Con SSO applicato, i controlli della sessione del tuo provider di identità governano le sessioni di amministrazione.

  3. Limita allowed_ips. Utilizza gli intervalli CIDR più piccoli che coprono i tuoi server MCP.

  4. Monitora i log. Configura gli avvisi su avvertenze, errori e modelli insoliti.

  5. Ruota le credenziali. Ruota i certificati secondo una pianificazione regolare o immediatamente se si sospetta un compromesso.

  6. Mantieni le immagini aggiornate. Applica gli aggiornamenti del gateway tempestivamente. Fissa le immagini per digest SHA256.

  7. Limita l'accesso alla rete. Il gateway e cloudflared dovrebbero avere solo l'accesso di rete richiesto.

  8. Limita l'ambito del server MCP. I server MCP dovrebbero esporre solo la funzionalità necessaria.

  9. Proteggi le credenziali a riposo. Applica le autorizzazioni di file appropriate, la crittografia a riposo e la gestione dei segreti alla directory tunnel-data/ (Compose) o al Secret delle credenziali (Helm).

Rispondere a un sospetto di violazione

Se sospetti che le credenziali del tunnel, le chiavi TLS o un altro aspetto del sistema sia stato compromesso:

  1. Arresta la distribuzione immediatamente (helm uninstall o docker compose down --timeout 0)

  2. Rimuovi i server MCP da Claude (Impostazioni organizzazione → Connettori)

  3. Archivia il tunnel tramite l'API (vedi Teardown, passaggio 3)

  4. Contatta Anthropic in modo che possano indagare

  5. Ruota le credenziali — esegui il provisioning di un tunnel nuovo, ruota i token OAuth sui tuoi server MCP

  6. Rivedi i registri prima di ripristinare il servizio

Risoluzione dei problemi

Errori di convalida IP

"IP validation failed" nei registri del gateway significa che l'upstream si è risolto in un IP esterno a allowed_ips. Controlla l'IP risolto:

Shell

dig +short docs-mcp.internal

Se l'IP è legittimo, aggiorna allowed_ips nella configurazione del gateway per includere l'intervallo CIDR corretto.

Tunnel non in connessione

Controlla i registri di cloudflared per gli errori. Cause comuni:

  • Token tunnel non valido

  • Firewall che blocca la porta 7844 TCP/UDP in uscita verso il bordo di Cloudflare

Verifica la connettività in uscita agli intervalli IP di Cloudflare: 198.41.192.0/19 e 2606:4700:a0::/44.

Avvisi sulla dimensione del buffer UDP

cloudflared potrebbe registrare failed to sufficiently increase receive buffer size. Si tratta di un problema di ottimizzazione del trasporto QUIC — consulta la documentazione del buffer UDP di quic-go per regolare.

Errori di certificato

Se l'handshake TLS non riesce, verifica che:

  • Il certificato del server non sia scaduto (validità di 90 giorni)

  • Il SAN del certificato corrisponda a *.<tunnel-domain>

  • Il certificato CA sia registrato presso Anthropic tramite l'API

  • Per Compose, i file di certificato sono leggibili da UID 65532

Instradamento di OAuth attraverso il tunnel (server di autenticazione dietro l'allowlist IP)

Problema: Il tuo server di autenticazione si trova dietro un allowlist di IP di origine. Il backend di Claude deve raggiungerlo per la scoperta OAuth, la registrazione del client e lo scambio di token, ma preferisci non inserire nella whitelist gli intervalli di IP in uscita di Anthropic.

Soluzione: configurazione split-endpoint. Instrada le chiamate OAuth backend-to-backend attraverso il tunnel. Mantieni l'endpoint /authorize rivolto al browser sul tuo nome host già inserito nella whitelist. Questo funziona perché Claude legge l'authorization_endpoint dai tuoi metadati di scoperta e reindirizza il browser dell'utente lì. Non ha bisogno di raggiungere quell'URL stesso.

Passaggio 1: Aggiungi una route del gateway per il tuo server di autenticazione

YAML — mcp-gateway.yaml

routes:
  mcp: http://your-mcp-server:8080
  auth: http://your-auth-server:8080

Passaggio 2: Servi i metadati di scoperta split-endpoint

Il /.well-known/oauth-authorization-server del tuo server di autenticazione deve restituire:

JSON

{
  "issuer": "https://auth.<tunnel-id>.tunnel.anthropic.com",
  "authorization_endpoint": "https://<your-allowlisted-host>/authorize",
  "token_endpoint": "https://auth.<tunnel-id>.tunnel.anthropic.com/token",
  "registration_endpoint": "https://auth.<tunnel-id>.tunnel.anthropic.com/register",
  "code_challenge_methods_supported": ["S256"]
}

Solo authorization_endpoint punta al tuo nome host esistente. Tutto il resto utilizza l'URL del tunnel.

Passaggio 3: Punta il tuo server MCP all'emittente del tunnel

Il /.well-known/oauth-protected-resource del tuo server MCP:

JSON

{
  "resource": "https://mcp.<tunnel-id>.tunnel.anthropic.com",
  "authorization_servers": [
    "https://auth.<tunnel-id>.tunnel.anthropic.com"
  ]
}

Disattivazione

Come disattivare un tunnel quando non è più necessario.

1. Ottieni l'ID del tunnel

Helm

TUNNEL_ID=$(kubectl get secret mcp-tunnel -n mcp-tunnel \
  -o jsonpath='{.data.tunnel-id}' | base64 -d)

Compose

TUNNEL_ID=$(sudo cat tunnel-data/tunnel-id)

2. Arresta la distribuzione

Helm: helm uninstall mcp-tunnel -n mcp-tunnel (nota: il Secret delle credenziali è stato creato dal Job di configurazione, non da Helm, quindi sopravvive alla disinstallazione)
​Compose: docker compose down

3. Archivia il tunnel

Genera prima un token API aggiornato e revocalo al termine.

Shell

read -rs API_TOKEN && export API_TOKEN

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/archive" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

4. Rimuovi le credenziali archiviate

Helm: kubectl delete secret mcp-tunnel -n mcp-tunnel
​Compose: sudo rm -rf tunnel-data

Ottenere aiuto

Contatta il tuo team di account Anthropic per assistenza.

Appendice: Configurazione del gateway

Il gateway legge la sua configurazione da un file YAML. In Docker Compose, scrivi questo file direttamente come config/mcp-gateway.yaml. In Helm, imposta questi campi sotto gateway.config.* nel tuo file values—il chart gestisce listen_addr, tls e tunnel_domain per te.

Campo

Descrizione

Predefinito

listen_addr

Indirizzo e porta su cui ascoltare

Obbligatorio

log_level

Verbosità della registrazione: debug, info, warn, error

info

shutdown_timeout

Tempo di attesa per le richieste in corso durante l'arresto graduale

30s

tunnel_domain

Dominio di base per la risoluzione delle route con prefisso

Nessuno

tls.cert_file

Percorso del certificato TLS

Obbligatorio

tls.key_file

Percorso della chiave privata TLS

Obbligatorio

routes

Mapping da nome host (o prefisso) a URL upstream

Obbligatorio

upstream.allowed_ips

Intervalli CIDR a cui il gateway può connettersi

Intervalli privati RFC 1918

upstream.disable_ip_validation

Disabilita completamente la convalida dell'indirizzo IP

false

upstream.tls.ca_file

Bundle CA per la convalida del TLS upstream

Nessuno

upstream.tls.include_system_cas

Considera attendibile il bundle CA di sistema per il TLS upstream

false

Per le route https://, impostare almeno uno tra upstream.tls.ca_file o upstream.tls.include_system_cas.

Appendice: API Tunnels

Per flussi di provisioning personalizzati, puoi chiamare direttamente l'API Tunnels. Tutte le richieste richiedono questi header:

Shell

-H "Authorization: Bearer $API_TOKEN"
-H "anthropic-version: 2023-06-01"
-H "anthropic-beta: mcp-tunnels-2026-02-24"

Crea un tunnel:

curl -X POST https://api.anthropic.com/v1/tunnels \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24" \
  -H "Content-Type: application/json" \
  -d '{}'

Elenca i tunnel:

curl https://api.anthropic.com/v1/tunnels \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Registra un certificato CA:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/certificates" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24" \
  -H "Content-Type: application/json" \
  -d "{\"ca_certificate_pem\": $(jq -Rs . < ca.crt)}"

Vedi Appendice: Requisiti dei certificati per scoprire cosa devono contenere i certificati CA e server.

Elenca i certificati CA:

curl "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/certificates" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Revoca un certificato CA:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/certificates/${CERT_ID}/revoke" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Rivela il token del tunnel:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/reveal_token" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Ruota il token del tunnel:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/rotate_token" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Archivia un tunnel:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/archive" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Appendice: Requisiti dei certificati

Se utilizzi il binario di configurazione (setup init / setup renew-cert), genera automaticamente certificati conformi e puoi saltare questa sezione. Questi requisiti si applicano se emetti certificati tramite la tua PKI.

Certificato CA — carica tramite POST /v1/tunnels/{id}/certificates. Un tunnel contiene al massimo due certificati CA attivi contemporaneamente, consentendo la rotazione senza tempi di inattività.

  • Codificato in PEM, singolo certificato, massimo 8 KB

  • Estensione BasicConstraints con CA:TRUE, contrassegnata come critica

  • Estensione SubjectKeyIdentifier presente

  • KeyUsage include keyCertSign

  • Entro il periodo di validità

  • RSA 2048-bit o superiore, oppure ECDSA P-256 o superiore; firma SHA-256 o più forte

Certificato server — presentato dal gateway durante l'handshake TLS interno. Non caricato su Anthropic.

  • Firmato direttamente da una CA registrata sul tunnel

  • Estensione AuthorityKeyIdentifier presente, corrispondente a SubjectKeyIdentifier della CA

  • SAN include un nome DNS corrispondente a <route>.<tunnel-domain> (un wildcard *.<tunnel-domain> copre tutti i percorsi)

  • Se presente un'estensione ExtendedKeyUsage, include serverAuth

  • Entro il periodo di validità

  • RSA 2048-bit o superiore, oppure ECDSA P-256 o superiore; firma SHA-256 o più forte

Riferimento: il binario di setup genera una CA ECDSA P-256 (validità 5 anni) e un certificato server RSA 4096-bit con SAN wildcard (validità 90 giorni).

Appendice: Riferimento CLI di setup

Il binario setup viene eseguito all'interno del contenitore gateway tramite docker compose run --rm setup <subcommand> (Compose) o come hook Helm e CronJob (Kubernetes).

setup init — crea un tunnel tramite l'API Tunnels, genera una CA e un certificato server, registra la CA e scrive tutti gli output.

Flag

Descrizione

Predefinito

--api-url

URL base API Anthropic. Letto anche da API_URL.

obbligatorio

--api-token

Token API con ambito tunnel. Letto anche da API_TOKEN.

obbligatorio

--output

Destinazione output: dir:/path o k8s-secret:NAME

k8s-secret:mcp-gateway

--cert-duration

Periodo di validità del certificato server

2160h (90 giorni)

--token-version

Stringa di rilevamento modifiche; un nuovo valore attiva la rotazione del token tunnel

nessuno

setup renew-cert — emette un nuovo certificato server firmato dalla CA memorizzata. Nessuna chiamata API richiesta.

Flag

Descrizione

Predefinito

--output

Destinazione output: dir:/path o k8s-secret:NAME

k8s-secret:mcp-gateway

--cert-duration

Periodo di validità del nuovo certificato

2160h (90 giorni)

--renew-before

Salta se il certificato esistente ha più di questo tempo prima della scadenza

0 (rinnova sempre)

Impostare --renew-before=720h rende il comando inoperante quando rimangono più di 30 giorni, adatto per l'esecuzione pianificata.

Articoli correlati
Hai ricevuto la risposta alla tua domanda?