MCP-Tunnel mit Helm bereitstellen

Das Anthropic Helm-Chart installiert den Tunnel-Stack als ein einzelnes Deployment und verbindet es mit deinem Tunnel: entweder einem, den der Setup-Hook des Charts für dich erstellt, oder einem bestehenden Tunnel, den du in der Console erstellt hast.



Bevor du beginnst

Du benötigst:

• Einen Tunnel. Mit programmatischem Zugriff erstellt der Setup-Hook des Charts einen für dich, wenn du keine Tunnel-ID angibst; um dich stattdessen mit einem bestehenden Tunnel zu verbinden, erstelle ihn in der Console und notiere die Tunnel-ID (tnl_...). Die manuelle Bereitstellung beginnt immer mit einem in der Console erstellten Tunnel; du benötigst außerdem dessen Tunnel-Token und Tunnel-Domain.
• Eine Möglichkeit für das Chart, sich bei der Tunnels API zu authentifizieren.
  • Programmatischer Zugriff (empfohlen). Die Setup-Komponente authentifiziert sich über Workload Identity Federation, ruft das Tunnel-Token ab, generiert eine CA, registriert sie bei Anthropic und speichert alles in einem Secret. Du benötigst eine Federation-Regel mit dem Scope workspace:manage_tunnels.
  • Manuell. Überspringe den programmatischen Zugriff. Du wirst das Tunnel-Token aus der Console abrufen, selbst eine CA und ein Serverzertifikat generieren, die CA in der Console registrieren und die Anmeldedaten dem Cluster als Secrets bereitstellen.
• Einen Kubernetes-Cluster, auf dem du mit helm und kubectl deployen kannst. Der Tab Ohne programmatischen Zugriff verwendet außerdem openssl (1.1.1 oder neuer).
• Ausgehende Netzwerkverbindung vom Cluster zu api.anthropic.com (443 TCP) und zum Tunnel-Edge (7844 TCP und UDP). Siehe die vollständigen Netzwerkanforderungen.
• Einen oder mehrere MCP-Server, die laufen und vom Cluster aus unter den Adressen erreichbar sind, die du unter gateway.config.routes konfigurierst. Wenn du noch keinen hast, verwende den Beispielserver.



Optional: Einen Beispiel-MCP-Server verwenden

Wenn du keinen MCP-Server zum Testen zur Verfügung hast, verwende diesen minimalen:

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

Die folgenden Installationsschritte weisen darauf hin, wo die entsprechende Route hinzugefügt werden muss.



Installation



Das Deployment verifizieren

Verifiziere Ende-zu-Ende von Anthropics Seite aus: Verwende https://<route>.<your-tunnel-domain>/<path> in einer Managed-Agent-Sitzung oder einer Messages-API-Anfrage, wobei <route> ein Schlüssel aus gateway.config.routes ist und <path> der Pfad ist, unter dem der Upstream-MCP-Server bereitsteht. Mit dem Beispiel-MCP-Server ist das https://echo.<your-tunnel-domain>/mcp. Siehe Die getunnelten MCP-Server verwenden für die Anfrageformate.

Wenn das fehlschlägt, prüfe die Pod-Logs (kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c mcp-proxy und -c cloudflared) und konsultiere die Fehlerbehebung.



Optionale Konfiguration



Egress mit NetworkPolicy einschränken

Ingress zum Proxy-Pod wird standardmäßig verweigert (networkPolicy.ingress.enabled: true). Um zusätzlich den Pod-Egress einzuschränken, setze networkPolicy.egress.enabled: true und fülle networkPolicy.egress.mcpServers mit Pod-Label-Selektoren oder CIDR-Bereichen, die deine Upstream-MCP-Server abdecken. Egress von cloudflared zum Tunnel-Edge wird separat über networkPolicy.egress.cloudflaredEgressCIDRs erlaubt.



Den Proxy anpassen

Felder unter gateway.config.* werden an die Proxy-Konfigurationsdatei durchgereicht. Häufige Anpassungen umfassen upstream.allowed_ips, log_level und upstream.tls. Siehe die Referenz zur Proxy-Konfiguration für die vollständige Feldliste. Das Chart setzt immer listen_addr, tls.cert_file und tls.key_file; sie in gateway.config zu setzen hat keine Wirkung.



Dein eigenes OIDC-Token bereitstellen

Standardmäßig projiziert das Chart ein Kubernetes-ServiceAccount-Token für die Setup-Komponente. Um ein Token von einem anderen Identity-Provider zu verwenden (wie SPIFFE, Vault oder einem Cloud-SDK-Sidecar), mounte es mit setup.extraVolumes und setup.extraVolumeMounts. Verweise dann mit api.wif.tokenFile auf den Mount-Pfad. Das Chart setzt ANTHROPIC_IDENTITY_TOKEN_FILE auf diesen Pfad, und die Setup-Komponente liest das Token von dort.



Upgrades

Übergib immer --version an helm upgrade, damit du nicht unerwartet ein neueres Chart abrufst.



Upgrade von Chart 1.x

Chart 2.0.0 verschiebt die Tunnel-ID von api.wif.tunnelId nach tunnel.id. Bearbeite vor dem Upgrade deine values.yaml: Verschiebe den tnl_...-Wert nach tunnel.id und entferne api.wif.tunnelId. tunnel.id nicht zu setzen ist sicher (die Setup-Komponente verwendet beim erneuten Ausführen die bereits im mcp-tunnel-Secret gespeicherte Tunnel-ID wieder), aber das explizite Verschieben hält deine values.yaml korrekt. Aktualisiere außerdem den Scope deiner Federation-Regel in der Console von org:manage_tunnels auf workspace:manage_tunnels.



Konfiguration ändern

Für routinemäßige Änderungen wie Routen, Replica-Anzahl oder 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



Das Tunnel-Token rotieren

Mit programmatischem Zugriff erhöhe tunnel.tokenVersion in values.yaml und führe das Upgrade mit --set setup.force=true durch. Die Setup-Komponente wird bei Upgrades nur erneut ausgeführt, wenn dies erzwungen wird:

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

Die Setup-Komponente authentifiziert sich mit Workload Identity Federation; es gibt kein API-Token, das widerrufen werden müsste.

Ohne programmatischen Zugriff klicke auf Rotate token auf der Tunnel-Detailseite in der Console und aktualisiere dann das mcp-tunnel-token-Secret:

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



Zertifikatserneuerung

Das Chart bietet Automatisierung, aber du bleibst dafür verantwortlich, den Ablauf zu überwachen und zu bestätigen, dass die Erneuerung abgeschlossen wird.

Mit programmatischem Zugriff erfolgt die Zertifikatserneuerung automatisch. Das Chart stellt einen CronJob bereit (benannt nach dem Helm-fullname mit dem Suffix -cert-renew), der täglich setup renew-cert ausführt (zu serverCert.cronSchedule, Standard 0 0 * * * UTC). Der Job ist ein No-op, es sei denn, das Zertifikat liegt innerhalb von serverCert.renewBefore vor dem Ablauf (Standard 30 Tage). Die Erneuerung erfolgt lokal: Der Job signiert ein neues Zertifikat mit der bereits im Secret gespeicherten CA, führt keine API-Aufrufe durch und benötigt nur das Kubernetes RBAC, das das Chart gewährt. Der Proxy lädt das Zertifikat per Hot-Reload aus dem Secret-Mount neu, sodass kein Deployment-Neustart erforderlich ist.

Ohne programmatischen Zugriff gibt es keinen CronJob. Signiere aus dem Verzeichnis mcp-tunnel/, das du nach der Installation behalten hast, ein neues Serverzertifikat mit der bestehenden CA (generiere die CA nicht neu):

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 -

Der Proxy lädt das Zertifikat per Hot-Reload aus dem Secret-Mount neu.



Nächste Schritte