--- title: Distribuire i tunnel MCP con Helm url: https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/deploy-helm description: Installa lo stack del tunnel su un cluster Kubernetes utilizzando il chart Helm di Anthropic. --- I "MCP tunnels" (tunnel MCP) sono in "research preview" (anteprima di ricerca). [Richiedi l'accesso](https://claude.com/form/mcp-tunnels) per provarli. Il chart Helm di Anthropic installa lo [stack del tunnel](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/concepts#components) come un singolo Deployment e lo collega al tuo tunnel: uno che l'hook di configurazione del chart crea per te, oppure un tunnel esistente che hai creato nella [Claude Console](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/console#create-a-tunnel). ## Prima di iniziare Ti servono: * **Un tunnel.** Con l'accesso programmatico, l'hook di configurazione del chart ne crea uno per te quando non fornisci un ID del tunnel; per collegarti invece a un tunnel esistente, [crealo nella Console](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/console#create-a-tunnel) e annota l'ID del tunnel (`tnl_...`). Il provisioning manuale parte sempre da un tunnel creato nella Console; ti servono anche il suo token del tunnel e il dominio del tunnel. * **Un modo per consentire al chart di autenticarsi presso la Tunnels API.** * **[Accesso programmatico](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/concepts#credential-provisioning) (consigliato).** Il [componente di configurazione](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/concepts#components) si autentica tramite Workload Identity Federation, recupera il token del tunnel, genera una CA, la registra presso Anthropic e memorizza tutto in un Secret. Ti serve una regola di federazione con ambito `workspace:manage_tunnels`. * **[Manuale](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/concepts#credential-provisioning).** Salta l'accesso programmatico. Dovrai [ottenere il token del tunnel dalla Console](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/console#get-the-connection-details), generare autonomamente una CA e un certificato del server, [registrare la CA nella Console](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate) e fornire le credenziali al cluster come Secret. * **Un cluster Kubernetes** su cui puoi effettuare il deployment con `helm` e `kubectl`. La scheda **Senza accesso programmatico** utilizza anche `openssl` (1.1.1 o successivo). * **Connettività di rete in uscita** dal cluster verso `api.anthropic.com` (443 TCP) e l'[edge del tunnel](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/concepts#components) (7844 TCP e UDP). Consulta i [requisiti di rete](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/overview#network-requirements) completi. * **Uno o più server MCP** in esecuzione e raggiungibili dal cluster agli indirizzi che configurerai in `gateway.config.routes`. Se non ne hai ancora uno, [usa il server di esempio](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server). ## Facoltativo: usa un server MCP di esempio Se non hai un server MCP disponibile per i test, usa questo server minimale: ```bash kubectl create namespace mcp-tunnel --dry-run=client -o yaml | kubectl apply -f - kubectl -n mcp-tunnel apply -f - <<'EOF' apiVersion: v1 kind: ConfigMap metadata: name: hello-mcp-src data: hello_server.py: | 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") --- apiVersion: apps/v1 kind: Deployment metadata: name: hello-mcp spec: replicas: 1 selector: matchLabels: { app: hello-mcp } template: metadata: labels: { app: hello-mcp } spec: containers: - name: hello-mcp image: python:3.13-slim command: ["sh", "-c", "pip install --quiet mcp && python /app/hello_server.py"] volumeMounts: - { name: src, mountPath: /app } ports: - { containerPort: 9000 } volumes: - name: src configMap: { name: hello-mcp-src } --- apiVersion: v1 kind: Service metadata: name: hello-mcp spec: selector: { app: hello-mcp } ports: - { port: 9000, targetPort: 9000 } EOF ``` I passaggi di installazione che seguono indicano dove aggiungere la route corrispondente. ## Installazione Il componente di configurazione scambia il token ServiceAccount proiettato del cluster tramite la tua regola di federazione, recupera il token del tunnel, genera una CA e un certificato del server e registra la CA presso Anthropic. Un CronJob giornaliero rinnova il certificato del server quando necessario, quindi non devi gestire manualmente alcun segreto. Segui [Usare WIF con Kubernetes](https://platform.claude.com/docs/it/manage-claude/wif-providers/kubernetes) per registrare l'issuer OIDC del tuo cluster e creare una regola di federazione. Il componente di configurazione viene eseguito con un proprio ServiceAccount nel namespace della release; il nome esatto segue la convenzione `fullname` di Helm, quindi per qualsiasi nome di release diverso da `mcp-tunnel`, esegui `helm template ... | grep -A2 'kind: ServiceAccount'` per verificarlo prima di creare la regola. Il resto di questa guida presuppone il nome di release `mcp-tunnel` nel namespace `mcp-tunnel`, dove il ServiceAccount è `mcp-tunnel-setup`. | Campo | Valore | | -------- | ------------------------------------------------------------------- | | Subject | `system:serviceaccount:mcp-tunnel:mcp-tunnel-setup` | | Audience | `api.anthropic.com` (il valore predefinito del chart; senza schema) | | Scope | `workspace:manage_tunnels` | L'audience predefinita del chart è `api.anthropic.com` senza schema, ma il modulo della regola di federazione nella Console suggerisce `https://api.anthropic.com`. I due valori devono corrispondere byte per byte, altrimenti l'autenticazione fallisce. Imposta l'audience della regola su `api.anthropic.com`, oppure imposta `api.wif.audience` in `values.yaml` su `https://api.anthropic.com`. Se il tunnel si trova in un workspace diverso da quello predefinito dell'organizzazione, [aggiungi anche il service account della regola a quel workspace](https://platform.claude.com/docs/it/manage-claude/workspaces#role-inheritance) (la Tunnels API autorizza in base alle appartenenze ai workspace del service account). Annota l'ID della regola (`fdrl_...`); lo imposterai come `api.wif.federationRuleId`. Il CronJob giornaliero di rinnovo del certificato utilizza un ServiceAccount separato (anch'esso derivato dal `fullname` di Helm) ma non chiama la Tunnels API; rinnova il certificato localmente e necessita solo dell'RBAC di Kubernetes, che il chart concede. La regola di federazione non deve coprirlo. ```bash helm show values \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.1.0 > values.yaml ``` Modifica `values.yaml` e imposta le chiavi `api.wif.*` con l'ID della regola di federazione e l'ID dell'organizzazione, oltre a una voce `routes` per ciascun [server MCP upstream](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/concepts#components): ```yaml values.yaml api: wif: federationRuleId: "fdrl_..." organizationId: "00000000-0000-0000-0000-000000000000" # Set when the tunnel is in a non-default workspace and the # rule's service account is a member of that workspace. # workspaceId: "wrkspc_..." tunnel: # Leave empty to have the setup hook create a tunnel during install. # Set to attach to an existing tunnel from the Console. id: "" # Increment to rotate the tunnel token on the next upgrade. # See the "Rotate the tunnel token" section. tokenVersion: "1" gateway: config: routes: docs: http://docs-mcp.internal:8080 search: http://search-mcp.internal:8080 ``` Con queste route, Claude raggiunge i server su `docs.` e `search.`. Alcune distribuzioni Kubernetes gestite allocano il CIDR dei Service al di fuori degli intervalli privati standard; se le tue route puntano a Service interni al cluster, aggiungi qui `gateway.config.upstream.allowed_ips` come descritto in [Convalida degli IP upstream](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/troubleshooting#upstream-ip-validation). Se stai usando il [server MCP di esempio](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server), imposta invece `routes` su `echo: http://hello-mcp:9000`. Esegui il rendering del chart ed esamina l'output secondo le pratiche di verifica della tua organizzazione: ```bash helm template mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.1.0 \ -n mcp-tunnel \ -f values.yaml > rendered.yaml ``` ```bash helm install mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.1.0 \ --namespace mcp-tunnel --create-namespace \ -f values.yaml ``` Il componente di configurazione viene eseguito come Job hook pre-install di Helm, quindi `helm install` resta bloccato finché non viene completato. In caso di successo, Helm elimina automaticamente il Job. Se `helm install` fallisce con un errore dell'hook, consulta [Errori di autenticazione del componente di configurazione](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/troubleshooting#setup-component-authentication-failures). Quando `tunnel.id` è vuoto, il componente di configurazione crea il tunnel nel workspace a cui punta la tua regola di federazione (il workspace predefinito dell'organizzazione, a meno che tu non imposti `api.wif.workspaceId`) e memorizza il suo ID e il suo dominio nel Secret `mcp-tunnel`. Trova il dominio che ti servirà per la [verifica](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/deploy-helm#verify-the-deployment) nella pagina dei dettagli del tunnel, che apri dalla pagina [Tunnel MCP](https://platform.claude.com/settings/workspaces/default/mcp-tunnels) (`platform.claude.com/settings/workspaces/default/mcp-tunnels`) nella Console. Nel selettore dei workspace nella barra laterale, seleziona il workspace che contiene il tunnel. Puoi anche leggere il dominio dal Secret: ```bash kubectl -n mcp-tunnel get secret mcp-tunnel \ -o jsonpath='{.data.tunnel-domain}' | base64 -d ``` La riesecuzione del componente di configurazione (durante gli [aggiornamenti](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/deploy-helm#upgrades) o la [rotazione del token](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/deploy-helm#rotate-the-tunnel-token)) riutilizza l'ID del tunnel memorizzato in questo Secret; non crea mai un secondo tunnel. I valori `api.wif.*` sono identificatori, non segreti, quindi memorizzarli nei Secret della cronologia delle release di Helm non costituisce un rischio. I dati sensibili a riposo sono quelli del Secret `mcp-tunnel` creato dal componente di configurazione, che contiene il token del tunnel e le chiavi private TLS. Applica a questo namespace le pratiche standard della tua organizzazione per la protezione dei Secret di Kubernetes. In questa modalità (`setup.enabled: false`) il chart non effettua chiamate API; il componente di configurazione non viene eseguito e non esiste alcun CronJob cert-renew. Usa questo percorso se preferisci non configurare Workload Identity Federation. [Crea il tunnel](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/console#create-a-tunnel) e [ottieni il token del tunnel dalla Console](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/console#get-the-connection-details). Annota il dominio del tunnel dalla pagina dei dettagli. Lo imposterai come `gateway.config.tunnel_domain`. Il proxy è in ascolto su WebSocket semplice, con il [TLS interno](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/concepts#components) trasportato all'interno di quel flusso utilizzando il certificato che generi qui. Il SAN del certificato del server deve includere `*.` come descritto nei [requisiti del certificato](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/reference#certificate-requirements). ```bash export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE mkdir -p mcp-tunnel/data cd mcp-tunnel # CA autofirmata. Estensioni esplicite affinché soddisfi i requisiti # del certificato indipendentemente dai default di openssl.cnf della distro. openssl req -x509 -newkey rsa:2048 -nodes \ -keyout data/ca.key -out data/ca.crt \ -days 3650 -subj "/CN=mcp-tunnel-ca" \ -addext "basicConstraints=critical,CA:TRUE" \ -addext "keyUsage=critical,keyCertSign,cRLSign" \ -addext "subjectKeyIdentifier=hash" # File di estensioni per il certificato del server. Usare -extfile (invece di # -copy_extensions, disponibile solo da OpenSSL 3.0+) lo mantiene funzionante su # OpenSSL 1.1.x. cat > data/tls.ext < Il chart legge chiavi specifiche; i nomi dei Secret sono configurabili, ma le chiavi no. Il seguente comando di creazione del namespace non ha effetto se il namespace esiste già (ad esempio, dal passaggio del [server MCP di esempio](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server)). ```bash kubectl create namespace mcp-tunnel --dry-run=client -o yaml | kubectl apply -f - kubectl -n mcp-tunnel create secret generic mcp-tunnel-token \ --from-literal=tunnel-token='eyJ...' kubectl -n mcp-tunnel create secret generic mcp-tunnel-cert \ --from-file=tls.crt=data/tls.crt \ --from-file=tls.key=data/tls.key ``` ```bash helm show values \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.1.0 > values.yaml ``` Modifica `values.yaml` e imposta le seguenti chiavi: ```yaml values.yaml setup: enabled: false external: tunnelTokenSecretName: mcp-tunnel-token # must contain key: tunnel-token serverCertSecretName: mcp-tunnel-cert # must contain keys: tls.crt, tls.key gateway: config: # Required when setup.enabled is false. Replace the placeholder with # the $TUNNEL_DOMAIN value you exported earlier. When setup.enabled # is true the chart injects this from the Secret as a -tunnel-domain # flag instead. tunnel_domain: YOUR_TUNNEL_DOMAIN_HERE routes: docs: http://docs-mcp.internal:8080 search: http://search-mcp.internal:8080 ``` Alcune distribuzioni Kubernetes gestite allocano il CIDR dei Service al di fuori degli intervalli privati standard; se le tue route puntano a Service interni al cluster, aggiungi qui `gateway.config.upstream.allowed_ips` come descritto in [Convalida degli IP upstream](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/troubleshooting#upstream-ip-validation). Se stai usando il [server MCP di esempio](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server), imposta invece `routes` su `echo: http://hello-mcp:9000`. ```bash helm template mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.1.0 \ -n mcp-tunnel \ -f values.yaml > rendered.yaml ``` ```bash helm install mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.1.0 \ --namespace mcp-tunnel --create-namespace \ -f values.yaml ``` ## Verifica il deployment Esegui una verifica end-to-end dal lato di Anthropic: usa `https://./` in una sessione di Managed Agent o in una richiesta alla Messages API, dove `` è una chiave di `gateway.config.routes` e `` è il percorso su cui il server MCP upstream risponde. Con il [server MCP di esempio](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server), è `https://echo./mcp`. Consulta [Usare i server MCP tramite tunnel](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers) per la struttura delle richieste. Se la verifica fallisce, controlla i log del pod (`kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c mcp-proxy` e `-c cloudflared`) e consulta la [Risoluzione dei problemi](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/troubleshooting). ## Configurazione facoltativa ### Limita il traffico in uscita con NetworkPolicy Il traffico in ingresso verso il pod del proxy è negato per impostazione predefinita (`networkPolicy.ingress.enabled: true`). Per limitare anche il traffico in uscita dal pod, imposta `networkPolicy.egress.enabled: true` e popola `networkPolicy.egress.mcpServers` con selettori di etichette dei pod o intervalli CIDR che coprano i tuoi server MCP upstream. Il traffico in uscita da cloudflared verso l'edge del tunnel è consentito separatamente tramite `networkPolicy.egress.cloudflaredEgressCIDRs`. ### Ottimizza il proxy I campi in `gateway.config.*` vengono passati al file di configurazione del proxy. Le modifiche comuni includono `upstream.allowed_ips`, `log_level` e `upstream.tls`. Consulta il riferimento sulla [configurazione del proxy](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/reference#proxy-configuration) per l'elenco completo dei campi. Il chart imposta sempre `listen_addr`, `tls.cert_file` e `tls.key_file`; impostarli in `gateway.config` non ha alcun effetto. ### Fornisci il tuo token OIDC Per impostazione predefinita, il chart proietta un token ServiceAccount di Kubernetes per il componente di configurazione. Per usare un token di un diverso provider di identità (come [SPIFFE](https://platform.claude.com/docs/it/manage-claude/wif-providers/spiffe), Vault o un sidecar di un SDK cloud), montalo con `setup.extraVolumes` e `setup.extraVolumeMounts`. Quindi fai puntare `api.wif.tokenFile` al percorso di montaggio. Il chart imposta `ANTHROPIC_IDENTITY_TOKEN_FILE` su quel percorso e il componente di configurazione legge il token da lì. ## Aggiornamenti Passa sempre `--version` a `helm upgrade` per non scaricare inaspettatamente un chart più recente. ### Aggiornamento dal chart 1.x Il chart 2.0.0 sposta l'ID del tunnel da `api.wif.tunnelId` a `tunnel.id`. Prima di aggiornare, modifica il tuo `values.yaml`: sposta il valore `tnl_...` in `tunnel.id` e rimuovi `api.wif.tunnelId`. Lasciare `tunnel.id` non impostato è sicuro (il componente di configurazione riutilizza alla riesecuzione l'ID del tunnel già memorizzato nel Secret `mcp-tunnel`), ma lo spostamento esplicito mantiene accurato il tuo `values.yaml`. Aggiorna inoltre nella Console l'ambito della tua regola di federazione da `org:manage_tunnels` a `workspace:manage_tunnels`. ### Modifica la configurazione Per modifiche di routine come route, numero di repliche o NetworkPolicy: ```bash helm upgrade mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.1.0 \ -n mcp-tunnel \ -f values.yaml ``` Mantieni un `values.yaml` completo invece di affidarti a `--reuse-values`. Il comportamento di deep-merge di Helm può non riuscire, senza segnalarlo, a rimuovere le route eliminate. ### Ruota il token del tunnel Con l'accesso programmatico, incrementa `tunnel.tokenVersion` in `values.yaml` ed esegui l'aggiornamento con `--set setup.force=true`. Il componente di configurazione viene rieseguito durante gli aggiornamenti solo se forzato: ```bash helm upgrade mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.1.0 \ -n mcp-tunnel \ -f values.yaml \ --set setup.force=true ``` Il componente di configurazione si autentica con Workload Identity Federation; non c'è alcun token API da revocare. Senza accesso programmatico, fai clic su **Rotate token** nella pagina dei dettagli del tunnel nella Console, quindi aggiorna il Secret `mcp-tunnel-token`: ```bash kubectl -n mcp-tunnel create secret generic mcp-tunnel-token \ --from-literal=tunnel-token='eyJ...' --dry-run=client -o yaml | kubectl apply -f - kubectl -n mcp-tunnel rollout restart deploy/mcp-tunnel ``` Facendo clic su **Rotate token** il token corrente viene invalidato immediatamente. Finché il Secret non viene aggiornato e il rollout non è completato, qualsiasi pod che si riavvia con il vecchio token (eviction, drain del nodo, OOM) non può riconnettersi. Aggiorna il Secret tempestivamente dopo la rotazione; per requisiti di disponibilità più rigorosi, usa l'accesso programmatico in modo che il chart gestisca la rotazione in modo atomico. ### Rinnovo del certificato Il chart fornisce l'automazione, ma resti responsabile del monitoraggio della scadenza e della conferma del completamento del rinnovo. Con l'accesso programmatico, il rinnovo del certificato è automatico. Il chart distribuisce un CronJob (denominato in base al `fullname` di Helm, con suffisso `-cert-renew`) che esegue `setup renew-cert` ogni giorno (secondo `serverCert.cronSchedule`, predefinito `0 0 * * *` UTC). Il job non ha effetto a meno che il certificato non si trovi entro `serverCert.renewBefore` dalla scadenza (predefinito 30 giorni). Il rinnovo è locale: il job firma un nuovo certificato con la CA già memorizzata nel Secret, non effettua chiamate API e necessita solo dell'RBAC di Kubernetes concesso dal chart. Il proxy ricarica a caldo il certificato dal mount del Secret, quindi non è necessario riavviare il Deployment. Senza accesso programmatico non esiste alcun CronJob. Dall'interno della directory `mcp-tunnel/` che hai conservato dopo l'installazione, firma un nuovo certificato del server con la CA esistente (non rigenerare la CA): ```bash 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 kubectl -n mcp-tunnel create secret generic mcp-tunnel-cert \ --from-file=tls.crt=data/tls.crt --from-file=tls.key=data/tls.key \ --dry-run=client -o yaml | kubectl apply -f - ``` Il proxy ricarica a caldo il certificato dal mount del Secret. ## Passaggi successivi Collega un server MCP upstream a un Managed Agent o alla Messages API. Indicazioni per l'hardening, rotazione delle credenziali e risposta alle violazioni. Diagnostica problemi di connettività, TLS e routing.