Zum Hauptinhalt springen

MCP Tunnels

Was ist das?

Verbinden Sie Claude sicher mit MCP-Servern in Ihrem privaten Netzwerk, ohne eingehende Ports zu öffnen oder Dienste im Internet freizulegen. MCP Tunnels befindet sich derzeit in der privaten Beta und nutzt den Tunnel-Dienst von Cloudflare.

Funktionsweise

MCP Tunnels erstellen eine verschlüsselte Verbindung zwischen Claude und Ihren internen MCP-Servern mit mehreren Sicherheitsebenen.

Wenn Claude einen MCP-Server in Ihrem privaten Netzwerk erreichen muss, wird die Anfrage durch einen sicheren Tunnel geleitet. Sie stellen zwei Komponenten bereit:

  • cloudflared (Cloudflares Tunnel-Agent)

  • MCP Gateway (bereitgestellt von Anthropic)

Cloudflared initiiert eine reine Ausgangsverbindung zu Cloudflares Edge. Es müssen keine eingehenden Ports in Ihrer Firewall geöffnet werden. Das MCP Gateway beendet eine innere TLS-Schicht, validiert Upstream-IPs zur Verhinderung von SSRF und leitet jede Anfrage basierend auf der Subdomain an den korrekten MCP-Server weiter.

Die Verbindung ist durch drei unabhängige Schichten gesichert: äußeres mTLS zwischen Anthropic und Cloudflare (mit IP-Validierung), inneres TLS, das Payloads End-to-End von Anthropics Backend zu Ihrem Gateway verschlüsselt (so konzipiert, dass Cloudflare keinen Zugriff auf MCP-Payloads hat), und OAuth-Authentifizierung auf der Anwendungsebene auf jedem MCP-Server.

Was Sie bereitstellen

cloudflared

Cloudflares Tunnel-Agent. Initiiert reine Ausgangsverbindungen — keine eingehenden Ports erforderlich.

MCP Gateway

Von Anthropic bereitgestellte Komponente, die innere TLS beendet, IPs validiert und Anfragen an Ihre MCP-Server weiterleitet.

Wichtige Sicherheitseigenschaften

  • Keine eingehenden Ports erforderlich. cloudflared initiiert nur Ausgangsverbindungen — Ihre Firewall bleibt geschlossen.

  • End-to-End-Verschlüsselung. Der Datenverkehr ist vom Backend von Anthropic zu Ihrem Gateway verschlüsselt. MCP-Payloads können von Cloudflare nicht gelesen werden.

  • Verteidigungsstrategie in der Tiefe. Mehrere Authentifizierungsebenen: mTLS, inneres TLS und OAuth auf der Anwendungsebene.

  • SSRF-Schutz. Das Gateway validiert Upstream-IPs, um Anfragefälschungsangriffe zu verhindern.

Diese Anleitung bietet Referenzbereitstellungen über Helm (für Kubernetes) und Docker Compose. Sie sind verantwortlich für die Anpassung an die Sicherheitsanforderungen Ihrer Organisation.

Gemeinsame Verantwortung

Die Sicherheit dieses Systems ist eine gemeinsame Verantwortung zwischen Anthropic und Ihrer Organisation.

Anthropic ist verantwortlich für:

  • Sicherstellen, dass nur Anthropic auf Tunnel zugreifen kann

  • Validierung Ihres CA-Zertifikats vor der Verbindung mit Ihrem Gateway

  • Sicherstellen, dass Claude nur Anfragen an Tunnel sendet, die Ihrer Organisation gehören

Sie sind verantwortlich für:

  • Befolgen Sie die Anleitung in diesem Dokument und alle nachfolgenden Anleitungen

  • Sicherung des Tunnel-Tokens und der privaten TLS-Schlüssel

  • Konfigurieren Sie Ihre MCP-Server zur Verwendung von OAuth-Authentifizierung wie in der MCP-Spezifikation beschrieben

  • Beschränken Sie den Zugriff auf Ihre Gateway-Hosts und MCP-Server auf angemessenes Personal

  • Benachrichtigen Sie Anthropic, wenn Sie vermuten, dass das System kompromittiert wurde (siehe Reaktion auf einen vermuteten Verstoß)

⚠️ Anmeldedatenrisiko. Wenn ein Angreifer Ihr Tunnel-Token und einen Ihrer privaten TLS-Schlüssel erhält, könnte er sich als Ihr Gateway ausgeben und MCP-Anfrage-Payloads lesen, einschließlich OAuth-Tokens. Schützen Sie diese Anmeldedaten gemäß den Sicherheitsanforderungen Ihrer Organisation – einschließlich Dateiberechtigungen, Verschlüsselung im Ruhezustand und Secrets-Management.

Voraussetzungen

  • Ein Bereitstellungsziel — ein Kubernetes-Cluster (für Helm) oder eine VM mit Docker und Docker Compose.

  • Ein Anthropic-API-Token für die Tunnels-API — generieren Sie einen von claude.ai → Organization Settings → Connectors → Tunnels API. Das Setup verwendet diesen Token, um den Tunnel bereitzustellen und Ihr CA-Zertifikat zu registrieren. Das Gateway benötigt es zur Laufzeit nicht. Widerrufen Sie es nach Abschluss des Setups.

  • Netzwerkzugriff — ausgehende Konnektivität gemäß der folgenden Tabelle.

  • MCP-Server — ein oder mehrere MCP-Server, die in Ihrem privaten Netzwerk ausgeführt werden und vom Gateway erreichbar sind.

Netzwerkanforderungen

Komponente

Ziel

Zweck

Setup (einmalig)

api.anthropic.com:443

(Port 443)

Tunnel-Bereitstellung

cloudflared

Cloudflare-Edge, Port 7844 TCP/UDP (198.41.192.0/19, 2606:4700:a0::/44)

Tunnelverbindung

MCP Gateway

Ihre MCP-Server

Upstream-Datenverkehr

Siehe Cloudflares Tunnel-Firewall-Dokumentation für die autoritative IP-Liste. Helm-Benutzer können diese Egress-Einschränkung durch Aktivierung des networkPolicy-Werts des Charts durchsetzen.

Wählen Sie Ihre Bereitstellungsmethode

MCP Tunnels können über Helm (Kubernetes) oder Docker Compose bereitgestellt werden. Wählen Sie die Methode, die zu Ihrer Infrastruktur passt.

⎈ Helm / Kubernetes

Empfohlen für die meisten Kunden. Automatisiert die Tunnel-Bereitstellung und Zertifikatverlängerung. Speichert Anmeldedaten als Secrets.

🐳 Docker Compose

Für Single-Host- oder VM-Bereitstellungen.

Helm / Kubernetes-Bereitstellung

1. Chart-Werte abrufen

Laden Sie die Standardwertedatei herunter. Sie enthält Kommentare, die jedes Feld erklären.

Shell

helm show values \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 > values.yaml

2. Konfigurieren Sie Ihre Routen

Bearbeiten Sie values.yaml und fügen Sie mindestens eine Route unter gateway.config.routes hinzu. Jede Route ordnet ein Subdomain-Präfix einer Upstream-MCP-Server-URL zu.

3. Überprüfen Sie die gerenderten Manifeste

Rendern Sie das Chart mit einem Platzhalter-Token, um die Kubernetes-Ressourcen vor der Installation zu überprüfen. Das Chart benötigt api.token zum Rendern, aber helm template ruft die API nicht auf.

Shell

helm template mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 \
  -n mcp-tunnel \
  -f values.yaml \
  --set api.token=placeholder > rendered.yaml

Überprüfen Sie rendered.yaml gemäß den Praktiken Ihrer Organisation zur Überprüfung von Manifesten von Drittanbietern.

4. Installieren Sie das Chart

Speichern Sie Ihr API-Token in einer Umgebungsvariablen und installieren Sie dann. Ein dedizierter Namespace wird zur Isolation empfohlen.

Shell

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

helm install mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 \
  --namespace mcp-tunnel --create-namespace \
  -f values.yaml \
  --set api.token="$API_TOKEN"

⚠️ Wichtig: Widerrufen Sie das API-Token nach Abschluss der Installation. Das Übergeben des Tokens über --set hält es aus Ihrer Wertedatei heraus, aber Helm zeichnet es immer noch in der Release-Historie auf (sh.helm.release.v1.* Secrets). Kubernetes Secrets sind standardmäßig nicht verschlüsselt, daher bleibt das Token bis zur Widerrufung aus dem Cluster wiederherstellbar.

5. Rufen Sie Ihre Tunnel-Domäne ab

Der Setup-Job schreibt die Tunnel-Domäne in ein Secret. Sie benötigen dies, um MCP-Server in Claude zu konfigurieren.

Shell

kubectl get secret mcp-tunnel -n mcp-tunnel \
  -o jsonpath='{.data.tunnel-domain}' | base64 -d

Sobald der Tunnel aktiv ist und läuft, verbinden Sie sich mit Claude.

Optional: NetworkPolicy aktivieren

Setzen Sie networkPolicy.enabled: true in Ihrer Wertedatei, um den Egress des Tunnel-Pods auf Netzwerkebene einzuschränken. Konfigurieren Sie networkPolicy.mcpServers mit Pod-Label-Selektoren oder CIDR-Bereichen für Ihre Upstream-MCP-Server. Die Richtlinie enthält bereits Egress-Regeln für cloudflared, um Cloudflares Edge zu erreichen. Ihr Cluster-CNI muss NetworkPolicy unterstützen – siehe die Wertedatei für ein Beispiel.

Optional: Gateway-Konfiguration

Felder unter gateway.config.* werden an die Konfigurationsdatei des Gateways weitergeleitet. Siehe Anhang: Gateway-Konfiguration für die vollständige Liste. Häufige Anpassungen sind upstream.allowed_ips, log_level und upstream.tls für https://-Routen. Um zusätzliche Dateien bereitzustellen, auf die die Konfiguration verweist (z. B. ein CA-Bundle für upstream.tls.ca_file), verwenden Sie gateway.extraVolumes und gateway.extraVolumeMounts.

Upgrades

Geben Sie immer --version bei helm upgrade an. Ohne dies ruft Helm die neueste Chart-Version aus der Registry ab, was möglicherweise nicht das ist, was Sie überprüft haben.

Für Konfigurationsänderungen (Routen, Replikationen, NetworkPolicy usw.) ist kein API-Token erforderlich. Der Setup-Job wird bei Upgrades übersprungen, es sei denn, Sie übergeben api.token:

Shell

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 \
  -n mcp-tunnel \
  -f values.yaml

Für die Tunnel-Token-Rotation erhöhen Sie tunnel.tokenVersion in Ihrer Wertedatei, generieren Sie ein neues API-Token und führen Sie ein Upgrade durch:

Shell

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 \
  -n mcp-tunnel \
  -f values.yaml \
  --set api.token="$API_TOKEN"

Widerrufen Sie das API-Token nach Abschluss des Upgrades.

Führen Sie eine vollständige Wertedatei bei, anstatt sich auf --reuse-values zu verlassen. Helm führt Map-Felder tief zusammen, daher schlägt das Löschen einer Route mit --reuse-values stillschweigend fehl.

Verwendung von helm template mit kubectl oder kustomize

Wenn Sie Manifeste lieber selbst rendern und anwenden möchten (über kubectl apply oder kustomize-Overlays), verwenden Sie externen Modus (setup.enabled: false). Stellen Sie den Tunnel separat bereit (siehe Anhang: Tunnels API) und geben Sie die Anmeldedaten als vorab erstellte Secrets an, auf die external.tunnelTokenSecretName und external.serverCertSecretName verweisen. Wenn Sie Ihre eigenen Zertifikate ausstellen, anstatt die Setup-Binärdatei zu verwenden, siehe Anhang: Zertifikatanforderungen.

Docker Compose-Bereitstellung

1. Bereiten Sie das Bereitstellungsverzeichnis vor

Shell

mkdir -p mcp-gateway/{config,tunnel-data}
cd mcp-gateway
sudo chown 65532:65532 tunnel-data

Das chown ermöglicht dem Container (der als UID 65532 ausgeführt wird), in das bind-gemountete Verzeichnis zu schreiben.

2. Erstellen Sie docker-compose.yaml

YAML

services:
  # One-time provisioning. Run with: docker compose run --rm setup
  setup:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-gateway@sha256:62ddf0897778c80997ca789189a8a0bd63df241659d661ff9d5b0e06b5ee1dcd
    entrypoint: ["/setup"]
    command:
      - init
      - --api-url=https://api.anthropic.com
      - --output=dir:/data
      - --token-version=1
    environment:
      - API_TOKEN
    volumes:
      - ./tunnel-data:/data
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    profiles: ["setup"]

  cloudflared:
    # Verify digest at https://hub.docker.com/r/cloudflare/cloudflared/tags
    image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
    command: tunnel --no-autoupdate --config /etc/cloudflared/config.yaml run
    environment:
      - TUNNEL_TOKEN
    volumes:
      - ./config/cloudflared-config.yaml:/etc/cloudflared/config.yaml:ro
    restart: unless-stopped
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    stop_grace_period: 30s
    logging:
      options:
        max-size: "10m"
        max-file: "3"

  mcp-gateway:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-gateway@sha256:62ddf0897778c80997ca789189a8a0bd63df241659d661ff9d5b0e06b5ee1dcd
    volumes:
      - ./config/mcp-gateway.yaml:/etc/mcp-gateway/config.yaml:ro
      - ./tunnel-data:/data:ro
    restart: unless-stopped
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    # Should match shutdown_timeout in mcp-gateway config
    stop_grace_period: 30s
    logging:
      options:
        max-size: "10m"
        max-file: "3"

Sicherheitsmaßnahmen: Ausführung ohne Root (UID 65532), schreibgeschütztes Dateisystem, keine Eskalation von Berechtigungen, alle Linux-Funktionen deaktiviert, Image-Pinning nach SHA256-Digest.

3. Tunnel bereitstellen

Shell

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

docker compose run --rm setup

Der Setup-Befehl erstellt einen Tunnel über die Tunnels API, generiert ein CA- und Serverzertifikat, registriert die CA bei Anthropic und schreibt alle Ausgaben in ./tunnel-data/.

Rufen Sie Ihre Tunnel-Domain für den nächsten Schritt ab:

Shell

sudo cat tunnel-data/tunnel-domain

⚠️ Wichtig: Widerrufen Sie das API-Token, bevor Sie fortfahren.

4. Gateway konfigurieren

Erstellen Sie config/mcp-gateway.yaml:

YAML

listen_addr: ":8080"
log_level: info
shutdown_timeout: 30s

# Your tunnel domain from Step 3
tunnel_domain: abcd1234.tunnel.anthropic.com

tls:
  cert_file: /data/tls.crt
  key_file: /data/tls.key

routes:
  # Replace with your actual MCP servers.
  # With tunnel_domain set, keys are subdomain prefixes.
  docs: http://docs-mcp.internal:8080
  search: http://search-mcp.internal:8080

upstream:
  allowed_ips:
    - 10.0.0.0/8

Siehe Anhang: Gateway-Konfiguration für alle verfügbaren Felder.

Erstellen Sie config/cloudflared-config.yaml:

YAML

ingress:
  - service: http://mcp-gateway:8080

5. Bereitstellung

Shell

export TUNNEL_TOKEN=$(sudo cat tunnel-data/tunnel-token)
docker compose up -d
docker compose logs -f

Verzeichnisstruktur:

mcp-gateway/
├── docker-compose.yaml
├── config/
│   ├── cloudflared-config.yaml
│   └── mcp-gateway.yaml
└── tunnel-data/
    ├── tunnel-id
    ├── tunnel-domain
    ├── tunnel-token
    ├── token-version
    ├── ca.crt
    ├── ca.key
    ├── tls.crt
    └── tls.key

Erwägen Sie, den privaten Schlüssel der CA und das Tunnel-Token in sichere Speicherung zu verschieben.

Für Multi-VM-Bereitstellungen: Kopieren Sie das Verzeichnis mcp-gateway/ auf jeden Host. Dasselbe Tunnel-Token und die Zertifikate funktionieren auf allen Replikationen.

Sobald der Tunnel läuft, verbinden Sie sich mit Claude.

Zertifikatverlängerung (Compose)

Das Serverzertifikat hat eine Gültigkeitsdauer von 90 Tagen. Erneuern Sie es vor Ablauf:

Shell

docker compose run --rm setup renew-cert --output=dir:/data

Das Gateway fragt die Zertifikatsdatei alle 30 Sekunden ab und lädt sie automatisch neu, wenn sie sich ändert. Siehe Anhang: Setup-CLI-Referenz für Flags, die diesen Befehl sicher für die Ausführung nach Plan machen.

Tunnel-Token-Rotation (Compose)

Bearbeiten Sie docker-compose.yaml, um --token-version zu erhöhen, und führen Sie dann das Setup mit einem neuen API-Token erneut aus:

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

docker compose run --rm setup

export TUNNEL_TOKEN=$(sudo cat tunnel-data/tunnel-token)
docker compose up -d cloudflared

Widerrufen Sie das API-Token, sobald die Rotation abgeschlossen ist.

Mit Claude verbinden

Sobald der Tunnel läuft, registrieren Sie Ihre MCP-Server in Claude, damit sie den Benutzern zur Verfügung stehen.

1. MCP-Server hinzufügen

Ein Organisationsadministrator navigiert zu Organization Settings → Connectors → Add → Custom → Web in claude.ai.

Geben Sie jeden MCP-Server mit seinem Tunnel-Hostnamen ein. Beispiel: docs.abcd1234.tunnel.anthropic.com. Das Subdomain-Präfix entspricht dem Route-Schlüssel aus Ihrer Gateway-Konfiguration.

2. Benutzer verbinden sich

Einzelne Benutzer navigieren zu Settings → Connectors und klicken auf Connect für jeden MCP-Server, den sie verwenden möchten.

Möchten Sie später weitere Server hinzufügen? Fügen Sie eine neue Route zu Ihrer Konfiguration hinzu, wenden Sie die Änderung an (helm upgrade oder docker compose restart mcp-gateway), und registrieren Sie den neuen Hostnamen in Claude. Keine Zertifikat- oder Cloudflared-Änderungen erforderlich. Das Wildcard-Zertifikat deckt alle Subdomains ab.

Best Practices für Sicherheit

  1. Erfordern Sie OAuth auf Ihren MCP-Servern. Der Tunnel und die TLS-Schichten schützen den Transport, aber wenn diese jemals kompromittiert werden, verhindert OAuth auf der Anwendungsebene immer noch unbefugte Tool-Aufrufe. Konfigurieren Sie jeden MCP-Server so, dass er OAuth-Authentifizierung erfordert, wie in der MCP-Spezifikation beschrieben.

  2. Aktivieren Sie SSO für Ihre claude.ai-Organisation. Tunnel-Tokens werden aus der claude.ai-Konsole generiert. Mit erzwungenem SSO steuern die Sitzungskontrollen Ihres Identitätsanbieters die Admin-Sitzungen.

  3. Beschränken Sie allowed_ips. Verwenden Sie die kleinsten CIDR-Bereiche, die Ihre MCP-Server abdecken.

  4. Überwachen Sie Protokolle. Richten Sie Benachrichtigungen für Warnungen, Fehler und ungewöhnliche Muster ein.

  5. Rotieren Sie Anmeldedaten. Rotieren Sie Zertifikate nach einem regelmäßigen Plan oder sofort, wenn ein Kompromiss vermutet wird.

  6. Halten Sie Images aktuell. Wenden Sie Gateway-Updates umgehend an. Heften Sie Images nach SHA256-Digest an.

  7. Begrenzen Sie den Netzwerkzugriff. Das Gateway und Cloudflared sollten nur den erforderlichen Netzwerkzugriff haben.

  8. Begrenzen Sie den MCP-Server-Umfang. MCP-Server sollten nur erforderliche Funktionalität verfügbar machen.

  9. Schützen Sie Anmeldedaten im Ruhezustand. Wenden Sie angemessene Dateiberechtigungen, Verschlüsselung im Ruhezustand und Secrets-Management auf das Verzeichnis tunnel-data/ (Compose) oder das Credentials Secret (Helm) an.

Reaktion auf einen vermuteten Verstoß

Wenn Sie vermuten, dass Ihre Tunnel-Anmeldedaten, TLS-Schlüssel oder ein anderer Aspekt des Systems kompromittiert wurde:

  1. Stoppen Sie die Bereitstellung sofort (helm uninstall oder docker compose down --timeout 0)

  2. Entfernen Sie MCP-Server aus Claude (Organization Settings → Connectors)

  3. Archivieren Sie den Tunnel über die API (siehe Teardown, Schritt 3)

  4. Kontaktieren Sie Anthropic, damit diese untersuchen können

  5. Rotieren Sie Anmeldedaten — stellen Sie einen neuen Tunnel bereit, rotieren Sie OAuth-Tokens auf Ihren MCP-Servern

  6. Überprüfen Sie die Protokolle, bevor Sie den Dienst wiederherstellen

Fehlerbehebung

IP-Validierungsfehler

"IP-Validierung fehlgeschlagen" in Gateway-Protokollen bedeutet, dass die Upstream-Auflösung zu einer IP außerhalb von allowed_ips führte. Überprüfen Sie die aufgelöste IP:

Shell

dig +short docs-mcp.internal

Wenn die IP legitim ist, aktualisieren Sie allowed_ips in Ihrer Gateway-Konfiguration, um den korrekten CIDR-Bereich einzuschließen.

Tunnel verbindet sich nicht

Überprüfen Sie die cloudflared-Protokolle auf Fehler. Häufige Ursachen:

  • Ungültiges Tunnel-Token

  • Firewall blockiert ausgehenden Port 7844 TCP/UDP zu Cloudflare Edge

Überprüfen Sie die ausgehende Konnektivität zu Cloudflares IP-Bereichen: 198.41.192.0/19 und 2606:4700:a0::/44.

UDP-Puffergröße-Warnungen

cloudflared kann failed to sufficiently increase receive buffer size protokollieren. Dies ist ein QUIC-Transport-Tuning-Problem — siehe die quic-go UDP-Puffer-Dokumentation, um dies anzupassen.

Zertifikatsfehler

Wenn der TLS-Handshake fehlschlägt, überprüfen Sie, dass:

  • Das Serverzertifikat nicht abgelaufen ist (90-Tage-Gültigkeit)

  • Der SAN des Zertifikats entspricht *.<tunnel-domain>

  • Das CA-Zertifikat ist bei Anthropic über die API registriert

  • Für Compose sind Zertifikatsdateien für UID 65532 lesbar

OAuth durch den Tunnel leiten (Auth-Server hinter IP-Allowlist)

Problem: Ihr Auth-Server befindet sich hinter einer Quell-IP-Allowlist. Claudes Backend muss ihn für OAuth-Erkennung, Client-Registrierung und Token-Austausch erreichen, aber Sie möchten Anthropics Egress-IP-Bereiche nicht auf die Whitelist setzen.

Lösung: Split-Endpoint-Konfiguration. Leiten Sie die Backend-zu-Backend-OAuth-Aufrufe durch den Tunnel. Behalten Sie den Browser-seitigen /authorize-Endpunkt auf Ihrem bestehenden auf der Whitelist stehenden Hostnamen bei. Dies funktioniert, weil Claude den authorization_endpoint aus Ihren Discovery-Metadaten liest und den Browser des Benutzers dorthin umleitet. Es muss diese URL selbst nicht erreichen.

Schritt 1: Fügen Sie eine Gateway-Route für Ihren Auth-Server hinzu

YAML — mcp-gateway.yaml

routes:
  mcp: http://your-mcp-server:8080
  auth: http://your-auth-server:8080

Schritt 2: Bereitstellung von Split-Endpoint-Discovery-Metadaten

Der /.well-known/oauth-authorization-server Ihres Auth-Servers muss zurückgeben:

JSON

{
  "issuer": "https://auth.<tunnel-id>.tunnel.anthropic.com",
  "authorization_endpoint": "https://<your-allowlisted-host>/authorize",
  "token_endpoint": "https://auth.<tunnel-id>.tunnel.anthropic.com/token",
  "registration_endpoint": "https://auth.<tunnel-id>.tunnel.anthropic.com/register",
  "code_challenge_methods_supported": ["S256"]
}

Nur authorization_endpoint verweist auf Ihren bestehenden Hostnamen. Alles andere verwendet die Tunnel-URL.

Schritt 3: Richten Sie Ihren MCP-Server auf den Tunnel-Issuer aus

Der /.well-known/oauth-protected-resource Ihres MCP-Servers:

JSON

{
  "resource": "https://mcp.<tunnel-id>.tunnel.anthropic.com",
  "authorization_servers": [
    "https://auth.<tunnel-id>.tunnel.anthropic.com"
  ]
}

Abbau

Wie man einen Tunnel außer Betrieb nimmt, wenn er nicht mehr benötigt wird.

1. Rufen Sie die Tunnel-ID ab

Helm

TUNNEL_ID=$(kubectl get secret mcp-tunnel -n mcp-tunnel \
  -o jsonpath='{.data.tunnel-id}' | base64 -d)

Compose

TUNNEL_ID=$(sudo cat tunnel-data/tunnel-id)

2. Beenden Sie die Bereitstellung

Helm: helm uninstall mcp-tunnel -n mcp-tunnel (Hinweis: das Credentials Secret wurde vom Setup Job erstellt, nicht von Helm, daher bleibt es nach der Deinstallation erhalten)
​Compose: docker compose down

3. Archivieren Sie den Tunnel

Generieren Sie zuerst ein neues API-Token und widerrufen Sie es nach Abschluss.

Shell

read -rs API_TOKEN && export API_TOKEN

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/archive" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

4. Entfernen Sie gespeicherte Anmeldedaten

Helm: kubectl delete secret mcp-tunnel -n mcp-tunnel
​Compose: sudo rm -rf tunnel-data

Hilfe erhalten

Wenden Sie sich an Ihr Anthropic-Kontoteam, um Unterstützung zu erhalten.

Anhang: Gateway-Konfiguration

Das Gateway liest seine Konfiguration aus einer YAML-Datei. In Docker Compose schreiben Sie diese Datei direkt als config/mcp-gateway.yaml. In Helm setzen Sie diese Felder unter gateway.config.* in Ihrer values-Datei — das Chart verwaltet listen_addr, tls und tunnel_domain für Sie.

Feld

Beschreibung

Standard

listen_addr

Adresse und Port zum Abhören

Erforderlich

log_level

Protokollierungsausführlichkeit: debug, info, warn, error

info

shutdown_timeout

Wartezeit für laufende Anfragen während des ordnungsgemäßen Herunterfahrens

30s

tunnel_domain

Basisdomäne für die Auflösung von Präfixrouten

Keine

tls.cert_file

Pfad zum TLS-Zertifikat

Erforderlich

tls.key_file

Pfad zum privaten TLS-Schlüssel

Erforderlich

routes

Zuordnung von Hostname (oder Präfix) zu Upstream-URL

Erforderlich

upstream.allowed_ips

CIDR-Bereiche, mit denen sich das Gateway verbinden darf

RFC 1918 private Bereiche

upstream.disable_ip_validation

IP-Validierung vollständig deaktivieren

false

upstream.tls.ca_file

CA-Bundle zur Validierung von Upstream-TLS

Keine

upstream.tls.include_system_cas

Vertrauen Sie dem System-CA-Bundle für Upstream-TLS

false

Für https:// Routen setzen Sie mindestens eines von upstream.tls.ca_file oder upstream.tls.include_system_cas.

Anhang: Tunnels API

Für benutzerdefinierte Bereitstellungs-Workflows können Sie die Tunnels API direkt aufrufen. Alle Anfragen erfordern diese Header:

Shell

-H "Authorization: Bearer $API_TOKEN"
-H "anthropic-version: 2023-06-01"
-H "anthropic-beta: mcp-tunnels-2026-02-24"

Tunnel erstellen:

curl -X POST https://api.anthropic.com/v1/tunnels \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24" \
  -H "Content-Type: application/json" \
  -d '{}'

Tunnel auflisten:

curl https://api.anthropic.com/v1/tunnels \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

CA-Zertifikat registrieren:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/certificates" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24" \
  -H "Content-Type: application/json" \
  -d "{\"ca_certificate_pem\": $(jq -Rs . < ca.crt)}"

Siehe Anhang: Zertifikatanforderungen für die Anforderungen an CA- und Serverzertifikate.

CA-Zertifikate auflisten:

curl "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/certificates" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

CA-Zertifikat widerrufen:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/certificates/${CERT_ID}/revoke" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Tunnel-Token anzeigen:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/reveal_token" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Tunnel-Token rotieren:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/rotate_token" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Tunnel archivieren:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/archive" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Anhang: Zertifikatanforderungen

Wenn Sie die Setup-Binärdatei verwenden (setup init / setup renew-cert), generiert sie automatisch konforme Zertifikate und Sie können diesen Abschnitt überspringen. Diese Anforderungen gelten, wenn Sie Zertifikate über Ihre eigene PKI ausstellen.

CA-Zertifikat — hochgeladen über POST /v1/tunnels/{id}/certificates. Ein Tunnel enthält maximal zwei aktive CA-Zertifikate gleichzeitig, was eine Rotation ohne Ausfallzeit ermöglicht.

  • PEM-kodiert, einzelnes Zertifikat, maximal 8 KB

  • BasicConstraints-Erweiterung mit CA:TRUE, als kritisch gekennzeichnet

  • SubjectKeyIdentifier-Erweiterung vorhanden

  • KeyUsage enthält keyCertSign

  • Innerhalb des Gültigkeitszeitraums

  • RSA 2048-Bit oder größer oder ECDSA P-256 oder größer; SHA-256 oder stärkere Signatur

Serverzertifikat — vom Gateway während des inneren TLS-Handshakes präsentiert. Nicht zu Anthropic hochgeladen.

  • Direkt von einer im Tunnel registrierten CA signiert

  • AuthorityKeyIdentifier-Erweiterung vorhanden, entspricht der SubjectKeyIdentifier der CA

  • SAN enthält einen DNS-Namen, der <route>.<tunnel-domain> entspricht (ein Wildcard *.<tunnel-domain> deckt alle Routen ab)

  • Falls eine ExtendedKeyUsage-Erweiterung vorhanden ist, enthält sie serverAuth

  • Innerhalb des Gültigkeitszeitraums

  • RSA 2048-Bit oder größer oder ECDSA P-256 oder größer; SHA-256 oder stärkere Signatur

Referenz: Die Setup-Binärdatei generiert eine ECDSA P-256 CA (5 Jahre Gültigkeit) und ein RSA 4096-Bit-Serverzertifikat mit Wildcard-SAN (90 Tage Gültigkeit).

Anhang: Setup-CLI-Referenz

Die setup-Binärdatei wird im Gateway-Container über docker compose run --rm setup <subcommand> (Compose) oder als Helm-Hook und CronJob (Kubernetes) ausgeführt.

setup init — erstellt einen Tunnel über die Tunnels API, generiert eine CA und ein Serverzertifikat, registriert die CA und schreibt alle Ausgaben.

Flag

Beschreibung

Standard

--api-url

Anthropic-API-Basis-URL. Auch aus API_URL gelesen.

erforderlich

--api-token

API-Token mit Tunnel-Bereich. Auch aus API_TOKEN gelesen.

erforderlich

--output

Ausgabeziel: dir:/path oder k8s-secret:NAME

k8s-secret:mcp-gateway

--cert-duration

Gültigkeitszeitraum des Serverzertifikats

2160h (90 Tage)

--token-version

Änderungserkennungszeichenfolge; ein neuer Wert löst die Tunnel-Token-Rotation aus

keine

setup renew-cert — stellt ein neues Serverzertifikat aus, das von der gespeicherten CA signiert ist. Kein API-Aufruf erforderlich.

Flag

Beschreibung

Standard

--output

Ausgabeziel: dir:/path oder k8s-secret:NAME

k8s-secret:mcp-gateway

--cert-duration

Gültigkeitszeitraum des neuen Zertifikats

2160h (90 Tage)

--renew-before

Überspringen, wenn das vorhandene Zertifikat länger als diese Zeit bis zum Ablauf verbleibt

0 (immer erneuern)

Das Setzen von --renew-before=720h macht den Befehl zu einem No-Op, wenn mehr als 30 Tage verbleiben, geeignet für die Ausführung nach Zeitplan.

Verwandte Artikel
Hat dies deine Frage beantwortet?