--- title: MCP-Tunnel-Referenz url: https://platform.claude.com/docs/de/agents-and-tools/mcp-tunnels/reference description: Proxy-Konfigurationsfelder, die Tunnels REST API, Zertifikatsanforderungen und die Setup-Komponente. --- „MCP tunnels" (MCP-Tunnel) befinden sich in der „research preview" (Forschungsvorschau). [Fordere Zugang an](https://claude.com/form/mcp-tunnels), um sie auszuprobieren. ## Proxy-Konfiguration Der [Proxy](https://platform.claude.com/docs/de/agents-and-tools/mcp-tunnels/concepts#components) liest seine Konfiguration aus `/etc/mcp-gateway/config.yaml` (Compose) oder aus der gerenderten ConfigMap (Helm, befüllt aus `gateway.config.*`). | Feld | Beschreibung | Standard | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | `listen_addr` | Adresse und Port, auf denen gelauscht wird. | Erforderlich | | `log_level` | Logging-Ausführlichkeit: `debug`, `info`, `warn` oder `error`. | `info` | | `shutdown_timeout` | Wie lange beim geordneten Herunterfahren auf laufende Anfragen gewartet wird. | `30s` | | `tunnel_domain` | Dem Tunnel zugewiesene Basisdomain. Wenn gesetzt, entfernt die Routensuche dieses Suffix von eingehenden Hostnamen, sodass `routes`-Schlüssel reine Subdomains (`wiki`) sein können. Wenn leer, müssen `routes`-Schlüssel exakte vollständige Hostnamen sein. | Erforderlich, wenn `routes`-Schlüssel reine Subdomains sind | | `tls.cert_file` | Pfad zum TLS-Serverzertifikat. | Erforderlich | | `tls.key_file` | Pfad zum privaten TLS-Serverschlüssel. | Erforderlich | | `routes` | Zuordnung von Subdomain oder vollständigem Hostnamen zu Upstream-URL. Siehe [Routenabgleich](https://platform.claude.com/docs/de/agents-and-tools/mcp-tunnels/reference#route-matching). | Erforderlich | | `upstream.allowed_ips` | IPv4-CIDR-Bereiche oder einzelne Adressen, zu denen der Proxy eine Verbindung herstellen darf. Schließt sich gegenseitig mit `disable_ip_validation` aus. | Private RFC1918-Bereiche | | `upstream.disable_ip_validation` | Deaktiviert die Upstream-IP-Validierung vollständig. Schließt sich gegenseitig mit `allowed_ips` aus. | `false` | | `upstream.tls.ca_file` | CA-Bundle zur Validierung von Upstream-TLS. | Keiner | | `upstream.tls.include_system_cas` | Zusätzlich dem System-CA-Bundle für Upstream-TLS vertrauen. | `false` | Setze für `https://`-Upstream-Routen mindestens eines von `upstream.tls.ca_file` oder `upstream.tls.include_system_cas`; andernfalls hat der Proxy keinen Vertrauensanker für das Upstream-Zertifikat. ### Routenabgleich `routes` ist eine flache String-Map (`map[string]string`), keine Liste. Der Proxy sucht den eingehenden Hostnamen zuerst per exakter Übereinstimmung, dann durch Entfernen des `tunnel_domain`-Suffixes und Abgleich der verbleibenden Subdomain. Der Abgleich berücksichtigt nur den Hostnamen; der Anfragepfad und der Query-String werden unverändert an den [Upstream-MCP-Server](https://platform.claude.com/docs/de/agents-and-tools/mcp-tunnels/concepts#components) weitergeleitet. Jeder Upstream-Wert muss exakt `scheme://host:port` sein. Der Port ist obligatorisch. Die Angabe eines Pfads wird beim Laden der Konfiguration mit `invalid upstream (must be scheme://host:port)` abgelehnt. ## Tunnels API Die Tunnels REST API befindet sich unter `/v1/tunnels` und unterstützt das Erstellen, Auflisten und Archivieren von Tunneln, das Registrieren von CA-Zertifikaten sowie das Anzeigen oder Rotieren des Tunnel-Tokens. Siehe die [Tunnels-API-Referenz](https://platform.claude.com/docs/de/api/beta/tunnels/list) für alle Endpunkte, Anfrage- und Antwortschemata sowie Beispiele. Die bisherige Admin-API-Oberfläche unter `/v1/organizations/tunnels` (Beta-Header `mcp-tunnels-2026-05-19`, Scope `org:manage_tunnels`) funktioniert während eines Migrationszeitraums weiterhin und bleibt in der [Admin-API-Referenz](https://platform.claude.com/docs/de/api/beta/organization/mcp_tunnels) mit einem Hinweis auf die Abkündigung dokumentiert. Zur Migration aktualisiere den Pfad auf `/v1/tunnels`, den Beta-Header auf `mcp-tunnels-2026-06-22` und den Scope deines WIF-Tokens auf `workspace:manage_tunnels`. Alle MCP-Tunnel-Endpunkte erfordern ein Bearer-Token mit dem Scope `workspace:manage_tunnels`, das über [Workload Identity Federation](https://platform.claude.com/docs/de/manage-claude/workload-identity-federation) bezogen wird. Admin-API-Keys werden nicht akzeptiert. Erforderliche Header bei jeder Anfrage: | Header | Wert | | ------------------- | -------------------------------------------------- | | `Authorization` | `Bearer ` (das per WIF ausgetauschte Token) | | `anthropic-version` | `2023-06-01` | | `anthropic-beta` | `mcp-tunnels-2026-06-22` | ## Zertifikatsanforderungen Die [Setup-Komponente](https://platform.claude.com/docs/de/agents-and-tools/mcp-tunnels/concepts#components) erzeugt automatisch konforme Zertifikate. Diese Anforderungen gelten nur, wenn du Zertifikate über deine eigene PKI ausstellst. ### CA-Zertifikat Hochladen mit `POST /v1/tunnels/{tunnel_id}/certificates`. Ein Tunnel kann bis zu zwei aktive CA-Zertifikate gleichzeitig halten, was eine Rotation ohne Ausfallzeit ermöglicht. * PEM-kodiert, einzelnes Zertifikat, bis zu 8 kB. * `BasicConstraints`-Erweiterung vorhanden mit `CA:TRUE`, als kritisch markiert. * `SubjectKeyIdentifier`-Erweiterung vorhanden. * `KeyUsage` enthält `keyCertSign`. * Innerhalb seines Gültigkeitszeitraums. * RSA 2048 Bit oder größer oder ECDSA P-256 oder größer, mit einer SHA-256- oder stärkeren Signatur. ### Serverzertifikat Wird vom Proxy während des [inneren TLS](https://platform.claude.com/docs/de/agents-and-tools/mcp-tunnels/concepts#components) präsentiert. * Direkt von einer registrierten CA signiert (keine Zwischenzertifikate). * `AuthorityKeyIdentifier`-Erweiterung vorhanden und mit dem `SubjectKeyIdentifier` der CA übereinstimmend. * Subject Alternative Name enthält einen DNS-Namen, der `.` entspricht. Ein Wildcard `*.` deckt alle Routen ab. * Falls die `ExtendedKeyUsage`-Erweiterung vorhanden ist, enthält sie `serverAuth`. * Innerhalb seines Gültigkeitszeitraums. * RSA 2048 Bit oder größer oder ECDSA P-256 oder größer, mit einer SHA-256- oder stärkeren Signatur. Die Setup-Komponente erzeugt eine ECDSA-P-256-CA mit fünfjähriger Gültigkeit und ein RSA-4096-Bit-Serverzertifikat mit einem Wildcard-SAN und 90-tägiger Gültigkeit. ## Setup-Komponente Die Setup-Komponente wird innerhalb des `mcp-proxy`-Images als `setup`-Binary ausgeliefert. Führe sie mit `docker compose run --rm setup ` (Compose) aus oder verlasse dich auf die Hooks und CronJobs des Charts (Helm). ### `setup init` Verbindet sich mit einem bestehenden Tunnel (oder erstellt einen, wenn keine Tunnel-ID angegeben wird), erzeugt dann eine CA und ein Serverzertifikat, registriert die CA, ruft das Tunnel-Token ab und schreibt alle Ausgaben an das Ziel. | Flag | Beschreibung | Standard | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | `--api-url` | Basis-URL der Claude API. Wird auch aus `API_URL` gelesen. | Erforderlich | | `--tunnel-id` | Tunnel-ID, mit der verbunden werden soll (`tnl_...`). Wird auch aus `TUNNEL_ID` gelesen. Wenn weggelassen, wird ein neuer Tunnel erstellt; eine bereits in der Ausgabe gespeicherte Tunnel-ID wird bei erneuten Ausführungen wiederverwendet. | Keiner (Tunnel erstellen) | | `--output` | Ausgabeziel: `dir:/path` oder `k8s-secret:NAME`. Das Helm-Chart übergibt `k8s-secret:`. | `k8s-secret:mcp-tunnel` (automatisch erkannt bei Ausführung in einem Kubernetes-Pod; andernfalls erforderlich) | | `--cert-duration` | Gültigkeitszeitraum des Serverzertifikats. | `2160h` (90 Tage) | | `--token-version` | String zur Änderungserkennung. Ein neuer Wert löst bei erneuter Ausführung eine Token-Rotation aus. Das Helm-Chart und das Compose-Beispiel übergeben beide `1` als Anfangswert. | Keiner | Der Befehl authentifiziert sich über [Workload Identity Federation](https://platform.claude.com/docs/de/manage-claude/workload-identity-federation). Er liest `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_WORKSPACE_ID` (optional) und genau eines von `ANTHROPIC_IDENTITY_TOKEN_FILE` oder `ANTHROPIC_IDENTITY_TOKEN`. Siehe die [WIF-Referenz](https://platform.claude.com/docs/de/manage-claude/wif-reference) für die aktuelle Semantik dieser Variablen; die Setup-Komponente leitet das Service-Konto aus der Federation-Regel ab und benötigt daher `ANTHROPIC_SERVICE_ACCOUNT_ID` nicht separat. ### `setup renew-cert` Stellt ein neues Serverzertifikat aus, das von der gespeicherten CA signiert ist. Führt keine API-Aufrufe durch. | Flag | Beschreibung | Standard | | ----------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | | `--output` | Ausgabeziel: `dir:/path` oder `k8s-secret:NAME`. Das Helm-Chart übergibt `k8s-secret:`. | `k8s-secret:mcp-tunnel` (automatisch erkannt bei Ausführung in einem Kubernetes-Pod; andernfalls erforderlich) | | `--cert-duration` | Gültigkeitszeitraum des neuen Zertifikats. | `2160h` (90 Tage) | | `--renew-before` | Überspringt die Erneuerung, wenn das bestehende Zertifikat noch mehr als diese Dauer gültig ist. | `0` (immer erneuern) | Mit `--renew-before=720h` wird der Befehl zu einem No-op, wenn noch mehr als 30 Tage Gültigkeit verbleiben, sodass er sicher nach einem festen Zeitplan ausgeführt werden kann.