MessagesMCP-Tunnel

MCP-Tunnels-Referenz

Proxy-Konfigurationsfelder, die Tunnels-REST-API, Zertifikatsanforderungen und die Setup-Komponente.

MCP-Tunnel befinden sich in der Research Preview. Zugang anfordern, um sie auszuprobieren.

Proxy-Konfiguration

Der Proxy liest seine Konfiguration aus /etc/mcp-gateway/config.yaml (Compose) oder 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 Graceful Shutdown auf laufende Anfragen gewartet wird.	`30s`
`tunnel_domain`	Basis-Domain, die dem Tunnel zugewiesen ist. Wenn gesetzt, entfernt die Routen-Suche dieses Suffix von eingehenden Hostnamen, sodass `routes`-Schlüssel reine Subdomains sein können (`wiki`). 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 Server-TLS-Zertifikat.	Erforderlich
`tls.key_file`	Pfad zum privaten Server-TLS-Schlüssel.	Erforderlich
`routes`	Map von Subdomain oder vollständigem Hostnamen zu Upstream-URL. Siehe Routen-Matching.	Erforderlich
`upstream.allowed_ips`	IPv4-CIDR-Bereiche oder einzelne Adressen, zu denen der Proxy Verbindungen aufbauen darf. Schließt sich gegenseitig mit `disable_ip_validation` aus.	Private RFC1918-Bereiche
`upstream.disable_ip_validation`	Upstream-IP-Validierung vollständig deaktivieren. Schließt sich gegenseitig mit `allowed_ips` aus.	`false`
`upstream.tls.ca_file`	CA-Bundle zur Validierung von Upstream-TLS.	Keine
`upstream.tls.include_system_cas`	Zusätzlich dem System-CA-Bundle für Upstream-TLS vertrauen.	`false`

Für https://-Upstream-Routen setze mindestens eines von upstream.tls.ca_file oder upstream.tls.include_system_cas; andernfalls hat der Proxy keinen Vertrauensanker für das Upstream-Zertifikat.

Routen-Matching

routes ist eine flache String-Map (map[string]string), keine Liste. Der Proxy sucht den eingehenden Hostnamen zuerst per exaktem Match, dann durch Entfernen des tunnel_domain-Suffixes und Matching der verbleibenden Subdomain. Der Match berücksichtigt nur den Hostnamen; der Request-Pfad und der Query-String werden unverändert an den Upstream-MCP-Server weitergeleitet.

Jeder Upstream-Wert muss exakt scheme://host:port sein. Der Port ist obligatorisch. Das Einfügen 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 Tunnels, das Registrieren von CA-Zertifikaten sowie das Anzeigen oder Rotieren des Tunnel-Tokens. Siehe die Tunnels-API-Referenz für alle Endpunkte, Request- und Response-Schemas und 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 mit einem Deprecation-Hinweis dokumentiert. Zum Migrieren 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-Tunnels-Endpunkte erfordern ein Bearer-Token mit dem Scope workspace:manage_tunnels, das über Workload Identity Federation bezogen wurde. Admin-API-Keys werden nicht akzeptiert.

Erforderliche Header bei jeder Anfrage:

Header	Wert
`Authorization`	`Bearer <token>` (das per WIF ausgetauschte Token)
`anthropic-version`	`2023-06-01`
`anthropic-beta`	`mcp-tunnels-2026-06-22`

Zertifikatsanforderungen

Die Setup-Komponente generiert 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-Extension vorhanden mit CA:TRUE, als kritisch markiert.
SubjectKeyIdentifier-Extension 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.

Server-Zertifikat

Wird vom Proxy während des inneren TLS präsentiert.

Direkt von einer registrierten CA signiert (keine Intermediates).
AuthorityKeyIdentifier-Extension vorhanden und passend zum SubjectKeyIdentifier der CA.
Subject Alternative Name enthält einen DNS-Namen, der <route>.<tunnel-domain> entspricht. Ein Wildcard *.<tunnel-domain> deckt alle Routen ab.
Wenn die ExtendedKeyUsage-Extension 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 generiert eine ECDSA-P-256-CA mit fünfjähriger Gültigkeit und ein RSA-4096-Bit-Server-Zertifikat 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 <subcommand> aus (Compose) 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), generiert dann eine CA und ein Server-Zertifikat, registriert die CA, ruft das Tunnel-Token ab und schreibt alle Ausgaben an das Ziel.

Flag	Beschreibung	Standard
`--api-url`	Claude-API-Basis-URL. 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.	Keine (Tunnel erstellen)
`--output`	Ausgabeziel: `dir:/path` oder `k8s-secret:NAME`. Das Helm-Chart übergibt `k8s-secret:<release>`.	`k8s-secret:mcp-tunnel` (automatisch erkannt, wenn in einem Kubernetes-Pod ausgeführt; andernfalls erforderlich)
`--cert-duration`	Gültigkeitszeitraum des Server-Zertifikats.	`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.	Keine

Der Befehl authentifiziert sich über 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 für die aktuelle Semantik dieser Variablen; die Setup-Komponente leitet den Service-Account aus der Federation-Regel ab, sodass sie ANTHROPIC_SERVICE_ACCOUNT_ID nicht separat benötigt.

`setup renew-cert`

Stellt ein neues Server-Zertifikat 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:<release>`.	`k8s-secret:mcp-tunnel` (automatisch erkannt, wenn in einem Kubernetes-Pod ausgeführt; andernfalls erforderlich)
`--cert-duration`	Gültigkeitszeitraum des neuen Zertifikats.	`2160h` (90 Tage)
`--renew-before`	Erneuerung überspringen, wenn das bestehende Zertifikat noch mehr als diese Dauer gültig ist.	`0` (immer erneuern)

Das Setzen von --renew-before=720h macht den 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.

Was this page helpful?

MessagesMCP-Tunnel

MCP-Tunnels-Referenz

Proxy-Konfigurationsfelder, die Tunnels-REST-API, Zertifikatsanforderungen und die Setup-Komponente.

MCP-Tunnel befinden sich in der Research Preview. Zugang anfordern, um sie auszuprobieren.

Proxy-Konfiguration

Der Proxy liest seine Konfiguration aus /etc/mcp-gateway/config.yaml (Compose) oder 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 Graceful Shutdown auf laufende Anfragen gewartet wird.	`30s`
`tunnel_domain`	Basis-Domain, die dem Tunnel zugewiesen ist. Wenn gesetzt, entfernt die Routen-Suche dieses Suffix von eingehenden Hostnamen, sodass `routes`-Schlüssel reine Subdomains sein können (`wiki`). 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 Server-TLS-Zertifikat.	Erforderlich
`tls.key_file`	Pfad zum privaten Server-TLS-Schlüssel.	Erforderlich
`routes`	Map von Subdomain oder vollständigem Hostnamen zu Upstream-URL. Siehe Routen-Matching.	Erforderlich
`upstream.allowed_ips`	IPv4-CIDR-Bereiche oder einzelne Adressen, zu denen der Proxy Verbindungen aufbauen darf. Schließt sich gegenseitig mit `disable_ip_validation` aus.	Private RFC1918-Bereiche
`upstream.disable_ip_validation`	Upstream-IP-Validierung vollständig deaktivieren. Schließt sich gegenseitig mit `allowed_ips` aus.	`false`
`upstream.tls.ca_file`	CA-Bundle zur Validierung von Upstream-TLS.	Keine
`upstream.tls.include_system_cas`	Zusätzlich dem System-CA-Bundle für Upstream-TLS vertrauen.	`false`

Routen-Matching

Tunnels-API

Alle MCP-Tunnels-Endpunkte erfordern ein Bearer-Token mit dem Scope workspace:manage_tunnels, das über Workload Identity Federation bezogen wurde. Admin-API-Keys werden nicht akzeptiert.

Erforderliche Header bei jeder Anfrage:

Header	Wert
`Authorization`	`Bearer <token>` (das per WIF ausgetauschte Token)
`anthropic-version`	`2023-06-01`
`anthropic-beta`	`mcp-tunnels-2026-06-22`

Zertifikatsanforderungen

Die Setup-Komponente generiert 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-Extension vorhanden mit CA:TRUE, als kritisch markiert.
SubjectKeyIdentifier-Extension 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.

Server-Zertifikat

Wird vom Proxy während des inneren TLS präsentiert.

Direkt von einer registrierten CA signiert (keine Intermediates).
AuthorityKeyIdentifier-Extension vorhanden und passend zum SubjectKeyIdentifier der CA.
Subject Alternative Name enthält einen DNS-Namen, der <route>.<tunnel-domain> entspricht. Ein Wildcard *.<tunnel-domain> deckt alle Routen ab.
Wenn die ExtendedKeyUsage-Extension 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 generiert eine ECDSA-P-256-CA mit fünfjähriger Gültigkeit und ein RSA-4096-Bit-Server-Zertifikat mit einem Wildcard-SAN und 90-tägiger Gültigkeit.

Setup-Komponente

`setup init`

Flag	Beschreibung	Standard
`--api-url`	Claude-API-Basis-URL. 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.	Keine (Tunnel erstellen)
`--output`	Ausgabeziel: `dir:/path` oder `k8s-secret:NAME`. Das Helm-Chart übergibt `k8s-secret:<release>`.	`k8s-secret:mcp-tunnel` (automatisch erkannt, wenn in einem Kubernetes-Pod ausgeführt; andernfalls erforderlich)
`--cert-duration`	Gültigkeitszeitraum des Server-Zertifikats.	`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.	Keine

`setup renew-cert`

Stellt ein neues Server-Zertifikat 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:<release>`.	`k8s-secret:mcp-tunnel` (automatisch erkannt, wenn in einem Kubernetes-Pod ausgeführt; andernfalls erforderlich)
`--cert-duration`	Gültigkeitszeitraum des neuen Zertifikats.	`2160h` (90 Tage)
`--renew-before`	Erneuerung überspringen, wenn das bestehende Zertifikat noch mehr als diese Dauer gültig ist.	`0` (immer erneuern)

Das Setzen von --renew-before=720h macht den 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.

Was this page helpful?

Proxy-Konfiguration

Routen-Matching

Tunnels-API

Zertifikatsanforderungen

CA-Zertifikat

Server-Zertifikat

Setup-Komponente

setup init

setup renew-cert

Proxy-Konfiguration

Routen-Matching

Tunnels-API

Zertifikatsanforderungen

CA-Zertifikat

Server-Zertifikat

Setup-Komponente

setup init

setup renew-cert

Proxy-Konfiguration

Routen-Matching

Tunnels-API

Zertifikatsanforderungen

CA-Zertifikat

Server-Zertifikat

Setup-Komponente

`setup init`

`setup renew-cert`

Proxy-Konfiguration

Routen-Matching

Tunnels-API

Zertifikatsanforderungen

CA-Zertifikat

Server-Zertifikat

Setup-Komponente

`setup init`

`setup renew-cert`