MCP-Tunnel mit Helm bereitstellen

Das Anthropic Helm-Chart installiert den Tunnel-Stack als einzelnes Deployment und verbindet ihn 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 stattdessen einen bestehenden Tunnel anzubinden, 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“ (Workload-Identitätsföderation), ruft das Tunnel-Token ab, generiert eine CA, registriert sie bei Anthropic und speichert alles in einem Secret. Du benötigst eine Föderationsregel mit dem Scope workspace:manage_tunnels.
  • Manuell. Überspringe den programmatischen Zugriff. Du holst das Tunnel-Token aus der Console, generierst selbst eine CA und ein Serverzertifikat, registrierst die CA in der Console und stellst die Zugangsdaten dem Cluster als Secrets bereit.
• Einen Kubernetes-Cluster, auf den du mit helm und kubectl deployen kannst. Der Tab Ohne programmatischen Zugriff verwendet zusätzlich openssl (1.1.1 oder neuer).
• Ausgehende Netzwerkkonnektivität 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. Falls 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 hinzuzufügen ist.

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, unter dem der Upstream-MCP-Server ausliefert. Mit dem Beispiel-MCP-Server ist das https://echo.<your-tunnel-domain>/mcp. Siehe Die getunnelten MCP-Server verwenden für die Anfrageformate.

Falls 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 befü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 sind 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.

Ein eigenes OIDC-Token bereitstellen

Standardmäßig projiziert das Chart ein Kubernetes-ServiceAccount-Token für die Setup-Komponente. Um ein Token von einem anderen Identitätsanbieter zu verwenden (etwa SPIFFE, Vault oder einem Cloud-SDK-Sidecar), mounte es mit setup.extraVolumes und setup.extraVolumeMounts. Richte dann 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 helm upgrade immer --version, damit du nicht unerwartet ein neueres Chart beziehst.

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 ungesetzt zu lassen ist unbedenklich (die Setup-Komponente verwendet bei erneuter Ausführung die bereits im Secret mcp-tunnel gespeicherte Tunnel-ID wieder), aber das explizite Verschieben hält deine values.yaml korrekt. Aktualisiere außerdem in der Console den Scope deiner Föderationsregel von org:manage_tunnels auf workspace:manage_tunnels.

Konfiguration ändern

Für Routineänderungen wie Routen, Replikazahl oder 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

Das Tunnel-Token rotieren

Mit programmatischem Zugriff erhöhe tunnel.tokenVersion in values.yaml und führe das Upgrade mit --set setup.force=true aus. Die Setup-Komponente läuft bei Upgrades nur erneut, wenn sie dazu gezwungen wird:

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

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

Ohne programmatischen Zugriff klicke auf der Tunnel-Detailseite in der Console auf Rotate token und aktualisiere dann das 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

Zertifikatserneuerung

Das Chart stellt Automatisierung bereit, 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 deployt einen CronJob (benannt nach dem Helm-fullname mit dem Suffix -cert-renew), der täglich setup renew-cert ausführt (gemäß serverCert.cronSchedule, Standard 0 0 * * * UTC). Der Job ist wirkungslos, solange das Zertifikat nicht innerhalb von serverCert.renewBefore vor dem Ablauf liegt (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, sodass kein Neustart des Deployments nötig ist.

Ohne programmatischen Zugriff gibt es keinen CronJob. Signiere aus dem Verzeichnis mcp-tunnel/ heraus, 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.

Nächste Schritte