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. Bei programmatischem Zugriff erstellt der Setup-Hook des Charts einen für dich, wenn du keine Tunnel-ID angibst; um stattdessen einen bestehenden Tunnel zu verwenden, erstelle ihn in der Console und notiere die Tunnel-ID (tnl_...). 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 holst das Tunnel-Token aus der Console, generierst selbst eine CA und ein Server-Zertifikat, registrierst die CA in der Console und stellst die Anmeldedaten dem Cluster als Secrets bereit.
• Einen Kubernetes-Cluster, auf dem du mit helm und kubectl deployen kannst. Der Tab Ohne programmatischen Zugriff verwendet zusätzlich 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 konfigurieren wirst. Wenn du noch keinen hast, verwende den Beispiel-Server.



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 der Anthropic-Seite aus: Verwende https://<route>.<your-tunnel-domain>/<path> in einer Managed-Agent-Sitzung oder einer Messages-API-Anfrage, wobei <route> ein Key aus gateway.config.routes ist und <path> das ist, was der Upstream-MCP-Server dort bereitstellt. 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, überprü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 ist 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.



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 (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 ziehst.



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 unbedenklich (die Setup-Komponente verwendet bei erneuter Ausführung die bereits im mcp-tunnel-Secret gespeicherte Tunnel-ID wieder), aber die explizite Verschiebung 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 Routineä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.2 \
  -n mcp-tunnel \
  -f values.yaml



Das Tunnel-Token rotieren

Mit programmatischem Zugriff erhöhe tunnel.tokenVersion in values.yaml und führe ein Upgrade mit --set setup.force=true durch. Die Setup-Komponente läuft bei Upgrades nur erneut, wenn sie erzwungen 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 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 deployt einen CronJob (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 läuft innerhalb von serverCert.renewBefore ab (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 Deployment-Neustart erforderlich ist.

Ohne programmatischen Zugriff gibt es keinen CronJob. Signiere aus dem mcp-tunnel/-Verzeichnis, das du nach der Installation behalten hast, ein neues Server-Zertifikat 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