MessagesMCP-Tunnel

MCP-Tunnel-Referenz

Copy page



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

Proxy-Konfiguration

Der Proxy liest seine Konfiguration aus /etc/mcp-gateway/config.yaml (Compose) oder aus der gerenderten ConfigMap (Helm, befüllt aus gateway.config.*).

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 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 für alle Endpunkte, Anfrage- und Antwortschemata sowie Beispiele.

Erforderliche Header bei jeder Anfrage:

Zertifikatsanforderungen

Die Setup-Komponente 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 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 <route>.<tunnel-domain> entspricht. Ein Wildcard *.<tunnel-domain> 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 <subcommand> (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.

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

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.