--- title: Distribuire 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 creato per te dall'hook di setup del chart, oppure un tunnel esistente che hai creato nella [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 setup del chart ne crea uno per te quando non fornisci un ID 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 serviranno anche il relativo token del tunnel e il dominio del tunnel. * **Un modo per il chart di autenticarsi alla Tunnels API.** * **[Accesso programmatico](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/concepts#credential-provisioning) (consigliato).** Il [componente di setup](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 servirà 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 tu stesso una CA e un certificato 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 distribuire con `helm` e `kubectl`. La scheda **Senza accesso programmatico** usa anche `openssl` (1.1.1 o successivo). * **Connettività di rete in uscita** dal cluster verso `api.anthropic.com` (443 TCP) e verso il [tunnel edge](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 sotto `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). ## Opzionale: 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 setup scambia il token ServiceAccount proiettato del cluster tramite la tua regola di federazione, recupera il token del tunnel, genera una CA e un certificato server e registra la CA presso Anthropic. Un CronJob giornaliero rinnova il certificato server quando necessario, così non devi gestire alcun segreto manualmente. 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 setup viene eseguito con il 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 confermarlo 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 usa 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.0.2 > values.yaml ``` Modifica `values.yaml` e imposta le chiavi `api.wif.*` con l'ID della regola di federazione e l'ID dell'organizzazione, più 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 Service CIDR al di fuori degli intervalli privati standard; se le tue route puntano a Service interni al cluster, aggiungi qui `gateway.config.upstream.allowed_ips` secondo [Validazione 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`. Renderizza il 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.0.2 \ -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.0.2 \ --namespace mcp-tunnel --create-namespace \ -f values.yaml ``` Il componente di setup viene eseguito come Job hook pre-install di Helm, quindi `helm install` si blocca finché non viene completato. In caso di successo Helm elimina automaticamente il Job. Se `helm install` fallisce con un errore di hook, consulta [Errori di autenticazione del componente di setup](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/troubleshooting#setup-component-authentication-failures). Quando `tunnel.id` è vuoto, il componente di setup 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`. Trovi 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 di dettaglio del tunnel, che apri dalla pagina [MCP tunnels](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 ``` Rieseguire il componente di setup (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 il Secret `mcp-tunnel` creato dal componente di setup, 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 setup non viene eseguito e non c'è 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 di dettaglio. Lo imposterai come `gateway.config.tunnel_domain`. Il proxy ascolta su WebSocket in chiaro, con il [TLS interno](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/concepts#components) trasportato all'interno di quello stream utilizzando il certificato che generi qui. Il SAN del certificato server deve includere `*.` secondo i [requisiti dei certificati](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 in OpenSSL 3.0+) mantiene il funzionamento 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.0.2 > 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 Service CIDR al di fuori degli intervalli privati standard; se le tue route puntano a Service interni al cluster, aggiungi qui `gateway.config.upstream.allowed_ips` secondo [Validazione 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.0.2 \ -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.0.2 \ --namespace mcp-tunnel --create-namespace \ -f values.yaml ``` ## Verifica la distribuzione Verifica end-to-end dal lato di Anthropic: usa `https://./` in una sessione 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 [Usa i server MCP in tunnel](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers) per i formati delle richieste. Se fallisce, controlla i log dei pod (`kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c mcp-proxy` e `-c cloudflared`) e consulta [Risoluzione dei problemi](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/troubleshooting). ## Configurazione opzionale ### Limita l'egress con NetworkPolicy L'ingress verso il pod del proxy è negato per impostazione predefinita (`networkPolicy.ingress.enabled: true`). Per limitare ulteriormente l'egress del pod, imposta `networkPolicy.egress.enabled: true` e popola `networkPolicy.egress.mcpServers` con selettori di label dei pod o intervalli CIDR che coprano i tuoi server MCP upstream. L'egress da cloudflared verso il tunnel edge è consentito separatamente tramite `networkPolicy.egress.cloudflaredEgressCIDRs`. ### Ottimizza il proxy I campi sotto `gateway.config.*` vengono passati direttamente al file di configurazione del proxy. Le regolazioni comuni includono `upstream.allowed_ips`, `log_level` e `upstream.tls`. Consulta il riferimento alla [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 setup. Per usare un token di un identity provider diverso (come [SPIFFE](https://platform.claude.com/docs/it/manage-claude/wif-providers/spiffe), Vault o un sidecar cloud-SDK), montalo con `setup.extraVolumes` e `setup.extraVolumeMounts`. Quindi punta `api.wif.tokenFile` al percorso di mount. Il chart imposta `ANTHROPIC_IDENTITY_TOKEN_FILE` su quel percorso e il componente di setup 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 setup riutilizza l'ID del tunnel già memorizzato nel Secret `mcp-tunnel` alla riesecuzione), ma lo spostamento esplicito mantiene accurato il tuo `values.yaml`. Aggiorna inoltre l'ambito della tua regola di federazione da `org:manage_tunnels` a `workspace:manage_tunnels` nella Console. ### 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.0.2 \ -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ò silenziosamente non rimuovere le route eliminate. ### Ruota il token del tunnel Con l'accesso programmatico, incrementa `tunnel.tokenVersion` in `values.yaml` e aggiorna con `--set setup.force=true`. Il componente di setup 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.0.2 \ -n mcp-tunnel \ -f values.yaml \ --set setup.force=true ``` 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, 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 ``` Fare clic su **Rotate token** invalida immediatamente il token corrente. Finché il Secret non viene aggiornato e il rollout non viene 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 che il rinnovo venga completato. 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` quotidianamente (secondo `serverCert.cronSchedule`, predefinito `0 0 * * *` UTC). Il job non ha effetto a meno che il certificato non sia 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 che il chart concede. Il proxy ricarica a caldo il certificato dal mount del Secret, quindi non è necessario alcun riavvio del Deployment. Senza accesso programmatico non c'è alcun CronJob. Dall'interno della directory `mcp-tunnel/` che hai conservato dopo l'installazione, firma un nuovo certificato 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.