MCP-Tunnel mit Helm bereitstellen

Das Anthropic-Helm-Chart installiert den Tunnel-Stack als einzelnes Deployment und verbindet ihn mit dem Tunnel, den du in der Console erstellt hast.

Bevor du beginnst

Du benötigst:

• Einen in der Console erstellten Tunnel. Führe zuerst Einen Tunnel erstellen aus und notiere die Tunnel-ID (tnl_...). Für die manuelle Bereitstellung benötigst du außerdem das Tunnel-Token und die Tunnel-Domain aus diesem Schritt.
• 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 org: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 außerdem 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 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.

Installieren

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> 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 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; das Setzen dieser Werte in gateway.config 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 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.

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 1.0.0 \
  -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 1.0.0 \
  -n mcp-tunnel \
  -f values.yaml \
  --set setup.force=true

Die Setup-Komponente authentifiziert sich mit Workload Identity Federation; es gibt kein API-Token zu widerrufen.

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