Distribuire i tunnel MCP con Helm

Il chart Helm di Anthropic installa lo stack del tunnel come un singolo Deployment e lo collega al tunnel che hai creato nella Console.

Prima di iniziare

Ti servono:

• Un tunnel creato nella Console. Completa prima Creare un tunnel e annota l'ID del tunnel (tnl_...). Per il provisioning manuale ti servono anche il token del tunnel e il dominio del tunnel ottenuti in quel passaggio.
• Un modo per consentire al chart di autenticarsi con la 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 archivia tutto in un Secret. Ti servirà una regola di federazione con scope org: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 effettuare il deploy 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 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 in gateway.config.routes. Se non ne hai ancora uno, usa il server di esempio.

Opzionale: usare 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 Managed Agent o in una richiesta alla Messages API, dove <route> è una chiave di gateway.config.routes e <path> è il percorso servito dal server MCP upstream. Con il server MCP di esempio, è https://echo.<your-tunnel-domain>/mcp. Consulta Usare i server MCP in tunnel 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 Risoluzione dei problemi.

Configurazione opzionale

Limitare l'egress con NetworkPolicy

L'ingress verso il pod del proxy è negato per impostazione predefinita (networkPolicy.ingress.enabled: true). Per limitare anche l'egress del pod, imposta networkPolicy.egress.enabled: true e popola networkPolicy.egress.mcpServers con selettori di label dei pod o intervalli CIDR che coprono i tuoi server MCP upstream. L'egress da cloudflared verso il tunnel edge è consentito separatamente tramite networkPolicy.egress.cloudflaredEgressCIDRs.

Ottimizzare il proxy

I campi sotto gateway.config.* vengono passati direttamente 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.

Fornire il proprio 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 evitare di scaricare inaspettatamente un chart più recente.

Modificare 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 1.0.0 \
  -n mcp-tunnel \
  -f values.yaml

Ruotare il token del tunnel

Con l'accesso programmatico, incrementa tunnel.tokenVersion in values.yaml ed esegui l'upgrade con --set setup.force=true. Il componente di setup viene rieseguito durante gli upgrade solo quando forzato:

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 1.0.0 \
  -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 rimani 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 è un no-op 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à archiviata nel Secret, non effettua chiamate API e necessita solo del RBAC di Kubernetes che il chart concede. 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.

Passaggi successivi