Tunnel MCP

I tunnel MCP ti permettono di connettere Claude a server Model Context Protocol (MCP) in esecuzione all'interno della tua rete privata. Il traffico fluisce su una connessione esclusivamente in uscita, quindi non è necessario aprire porte del firewall in ingresso, esporre servizi alla rete Internet pubblica o inserire gli intervalli IP di Anthropic nella lista consentita della tua origine.

Per l'idoneità a Zero Data Retention e HIPAA BAA, consulta API e conservazione dei dati.



Come funziona

Lo stack del tunnel è composto da due componenti che vengono eseguiti all'interno della tua rete:

• cloudflared: il connettore di tunnel open source di Cloudflare. Avvia connessioni esclusivamente in uscita verso il tunnel edge e trasporta il traffico crittografato da Anthropic al tuo proxy.
• Proxy: il componente di routing di Anthropic. Termina il TLS interno, convalida che gli IP upstream rientrino in un intervallo consentito e instrada ogni richiesta al corretto server MCP upstream in base al nome host.

Ogni server MCP che esponi ottiene un nome host sotto il dominio del tuo tunnel (ad esempio, docs.<your-tunnel-domain>). Colleghi questi nomi host a una sessione Managed Agent nella Claude Console, oppure li passi alla Messages API tramite il connettore MCP.



Prerequisiti

Prima di eseguire il deployment, assicurati di avere:

• Una destinazione di deployment: un cluster Kubernetes, oppure una VM con Docker e Docker Compose.
• Un tunnel. Creane uno nella Claude Console (consulta Creare un tunnel) o tramite l'API; l'hook di setup del chart Helm può anche crearne uno per te durante l'installazione.
• Un modo per il tuo stack di autenticarsi alla Tunnels API. Scegli una delle seguenti opzioni:
  • Accesso programmatico (consigliato). Configura la Workload Identity Federation quando crei il tunnel. Il tuo stack genera token API a breve durata dal tuo provider di identità, recupera il token del tunnel e genera e registra automaticamente un certificato CA. Richiede l'autorizzazione a gestire le regole di federazione, un issuer OIDC registrato e una regola di federazione con lo scope workspace:manage_tunnels.
  • Manuale. Fornisci tu stesso le credenziali statiche: il token del tunnel dalla Console e un certificato server firmato da una CA che registri lì. Consulta Ottenere i dettagli di connessione e Aggiungere un certificato CA.
• Uno o più server MCP in esecuzione nella tua rete privata. Consulta Server MCP remoti per alcuni esempi.
• Connettività in uscita come indicato in Requisiti di rete.



Requisiti di rete



Modello di sicurezza



Livelli di sicurezza

Tre livelli indipendenti proteggono ogni richiesta:

Il trasporto del tunnel viene eseguito sulla rete di Cloudflare. Poiché il proxy termina il TLS interno utilizzando un certificato che solo tu possiedi, Cloudflare non può leggere i payload delle richieste o delle risposte. Anthropic non si connette a un tunnel finché non viene registrato un certificato CA, quindi i payload sono sempre crittografati quando attraversano la rete di Cloudflare. Cloudflare riceve comunque i metadati di connessione; consulta Cosa può osservare il provider di trasporto.



Modello di responsabilità condivisa



Cosa può osservare il provider di trasporto

Cloudflare fornisce il trasporto in uscita. Non può leggere i payload delle richieste o delle risposte MCP, ma riceve i seguenti metadati di connessione:

• l'indirizzo IP di uscita dell'host che esegue cloudflared
• un fingerprint dell'host cloudflared
• tempistiche di connessione e volume di byte
• il sottodominio *.tunnel.anthropic.com assegnato al tuo tunnel

L'accordo di Anthropic con Cloudflare limita l'uso di questa telemetria da parte di Cloudflare. Cloudflare agisce come subprocessore per questa anteprima di ricerca.



Eseguire il deployment di un tunnel

Se sei nuovo ai tunnel MCP, inizia con la guida rapida per ottenere un tunnel funzionante in locale prima di configurare un deployment di produzione.

Come scegliere tra le opzioni:

• Destinazione di deployment
  • Helm quando esegui il deployment su Kubernetes.
  • Docker Compose per un singolo host o per test in locale.
• Autenticazione per il setup
  • Accesso programmatico (tramite Workload Identity Federation) quando disponi di un provider di identità OIDC come un cluster Kubernetes, un IAM cloud o SPIFFE.
  • Credenziali manuali quando non ne disponi, o quando stai eseguendo dei test.



Usare i server MCP attraverso il tunnel

Una volta che il tuo tunnel è attivo (ha un certificato CA attivo e il tuo stack del tunnel è connesso), i server MCP upstream sono raggiungibili dai Claude Managed Agents e dalla Messages API.

In entrambi i casi, il tunnel trasporta il traffico crittografato verso il tuo server MCP ma non si autentica presso di esso. Se il server MCP upstream richiede una propria autenticazione (OAuth, bearer token), forniscila nello stesso modo in cui lo faresti per qualsiasi altro server MCP; è indipendente dal tunnel.



Managed Agents (Console)

1. In Managed Agents > Sessions, crea una sessione e scegli Create new agent in modo da poter modificare l'elenco dei server MCP.
2. Fai clic su + MCP Server e apri il menu a discesa. I tunnel nel workspace della sessione che hanno almeno un certificato attivo appaiono in cima all'elenco, sopra il catalogo dei connettori pubblici.
3. Seleziona il tunnel e fornisci il Subdomain che il tuo proxy instrada verso un server MCP specifico, e il Path che il server MCP upstream si aspetta. La riga Resolves to mostra l'URL esatto.



Messages API

Passa l'URL del server MCP upstream nell'array mcp_servers, nello stesso modo di qualsiasi altro server MCP remoto. Il corpo della richiesta e l'header anthropic-beta seguono il formato standard del connettore MCP; solo l'url è specifico del tunnel. L'esempio seguente utilizza l'header beta mcp-client del connettore MCP, che è separato dalla beta mcp-tunnels utilizzata dalla Tunnels API. Usa una chiave API per il workspace in cui è stato creato il tunnel (Console Settings > API keys).

L'host dell'URL è <subdomain>.<your-tunnel-domain>. Il percorso dipende dal tuo server MCP upstream, non dal tunnel: il trasporto streamable-http di FastMCP serve su /mcp, e altri server possono usare / o un percorso personalizzato (controlla la documentazione del server). Il proxy inoltra il percorso senza modificarlo.

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1000,
    messages=[{"role": "user", "content": "Use the hello tool to greet tunnel."}],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://echo.YOUR_TUNNEL_DOMAIN_HERE/mcp",
            "name": "echo",
        }
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "echo"}],
    betas=["mcp-client-2025-11-20"],
)

print(response)

Per l'autenticazione al server MCP upstream (authorization_token) e altre opzioni di mcp_servers, consulta Connettore MCP.



Prossimi passi