Distribuisci i tunnel MCP con Helm

Il chart Helm di Anthropic installa lo stack del tunnel 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.



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 del tunnel; per collegarti invece a un tunnel esistente, crealo nella Console e annota l'ID del tunnel (tnl_...). Il provisioning manuale parte sempre da un tunnel creato nella Console; ti serviranno anche il suo token del tunnel e il dominio del tunnel.
• Un modo per il chart di autenticarsi alla Tunnels API.
  • Accesso programmatico (consigliato). Il componente di setup 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. Salta l'accesso programmatico. Dovrai ottenere il token del tunnel dalla Console, generare tu stesso una CA e un certificato server, registrare la CA nella Console e fornire le credenziali al cluster come Secret.
• Un cluster Kubernetes su cui puoi eseguire il deployment 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 il tunnel edge (7844 TCP e UDP). Consulta i requisiti di rete 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.



Opzionale: Usa un server MCP di esempio

Se non hai un server MCP disponibile per i test, usa questo server minimale:

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



Verifica il deployment

Verifica end-to-end dal lato di Anthropic: usa https://<route>.<your-tunnel-domain>/<path> in una sessione di Managed Agent o in una richiesta alla Messages API, dove <route> è una chiave di gateway.config.routes e <path> è il percorso su cui il server MCP upstream risponde. Con il server MCP di esempio, è https://echo.<your-tunnel-domain>/mcp. Consulta Usa i server MCP attraverso il tunnel per la struttura delle richieste.

Se la verifica 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.



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 al file di configurazione del proxy. Le modifiche più comuni includono upstream.allowed_ips, log_level e upstream.tls. Consulta il riferimento alla configurazione del proxy 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, Vault o un sidecar cloud-SDK), montalo con setup.extraVolumes e setup.extraVolumeMounts. Poi fai puntare 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.



Aggiorna 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 nuova esecuzione), ma lo spostamento esplicito mantiene accurato il tuo values.yaml. Aggiorna anche 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:

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



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:

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 2.0.1 \
  -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, poi aggiorna il Secret mcp-tunnel-token:

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



Rinnovo del certificato

Il chart fornisce l'automazione, ma rimani 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 (a 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 del 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 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):

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.



Prossimi passi