Distribuire 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 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 relativo 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 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 (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 la distribuzione

Verifica end-to-end dal lato di Anthropic: usa https://<route>.<your-tunnel-domain>/<path> in una sessione 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 in tunnel 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.

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 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. 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:

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

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.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:

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 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):

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