Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Secure MCP Tunnel

Verbinde private MCP-Server mit unterstützten OpenAI-Produkten, ohne die Server über das öffentliche Internet zugänglich zu machen.

Mit Secure MCP Tunnel kannst du private MCP-Server mit unterstützten OpenAI-Produkten verbinden, ohne Firewall-Ports für eingehende Verbindungen zu öffnen oder die Server über das öffentliche Internet zugänglich zu machen. Führe tunnel-client in einem Netzwerk aus, aus dem dein MCP-Server bereits erreichbar ist. Der Client baut eine ausgehende HTTPS-Verbindung zu OpenAI auf, ruft ausstehende MCP-Anfragen ab, leitet sie lokal weiter und sendet die Antworten durch denselben Tunnel zurück.

Secure MCP Tunnel unterstützt private MCP-Verbindungen, auch zum Testen eigener MCP-Server. Das Einreichen und Verteilen öffentlicher Plugins wird nicht unterstützt. Öffentliche Plugins benötigen einen stabilen, öffentlich erreichbaren HTTPS-Endpunkt für MCP. Wenn der MCP-Server privat bleiben muss, stelle einen öffentlichen HTTPS-Proxy bereit, der Anfragen an ihn weiterleitet. Die Anforderungen an Endpunkte und Authentifizierung findest du im Leitfaden zum Einreichen öffentlicher Plugins.

Was ist ein MCP-Tunnel?

Ein MCP-Tunnel ist eine rein ausgehende Verbindung von einem Host in deinem Netzwerk zu einem von OpenAI gehosteten MCP-Endpunkt. Nutze ihn, wenn dein MCP-Server privat ist, vor Ort oder hinter einer Firewall läuft und ChatGPT, Codex, die Responses API oder eine andere unterstützte OpenAI-Oberfläche ihn aufrufen muss.

Mit Secure MCP Tunnel bleibt der MCP-Server privat. Unterstützte OpenAI-Produkte können wie gewohnt MCP-Anfragen stellen. tunnel-client fragt bei OpenAI ausstehende Anfragen ab, leitet die MCP-Anfragen lokal weiter und sendet die Antworten durch denselben Tunnel zurück.

Wann sich Secure MCP Tunnel eignet

  • Dein MCP-Server läuft in einem privaten Netzwerk, vor Ort, auf einem Entwicklungsrechner oder hinter bestehenden Zugriffskontrollen.
  • ChatGPT, Codex, die Responses API oder eine andere unterstützte OpenAI-Oberfläche soll den MCP-Server nutzen können, ohne dass du ihn öffentlich zugänglich machst.
  • Dein Netzwerk erlaubt dem Host, auf dem tunnel-client läuft, ausgehende HTTPS-Anfragen an api.openai.com:443 (Standard) oder an mtls.api.openai.com:443 (bei konfiguriertem mTLS für die Steuerungsebene). Der Host kann außerdem den privaten MCP-Server erreichen.
  • Eine Einführung in die Grundlagen von MCP findest du im Leitfaden zu MCP-Servern.

So funktioniert der Tunnel

  1. Erstelle oder verwalte in den Tunneleinstellungen der Plattform einen von OpenAI gehosteten MCP-Tunnelendpunkt.
  2. Führe tunnel-client in dem Netzwerk aus, aus dem dein privater MCP-Server erreichbar ist.
  3. Konfiguriere tunnel-client mit der Tunnelidentität und der Adresse des privaten MCP-Servers.
  4. OpenAI-Produkte senden MCP-Anfragen an den von OpenAI gehosteten Tunnelendpunkt.
  5. tunnel-client ruft ausstehende Anfragen per Long Polling ab, leitet jede JSON-RPC-Anfrage an den privaten MCP-Server weiter und sendet die Antwort durch den Tunnel zurück.

Der private MCP-Server benötigt keinen öffentlichen Listener. Über den von OpenAI gehosteten Endpunkt können unterstützte Produkte wie gewohnt MCP-Anfragen stellen. Der Verbindungsaufbau geht dabei von deinem Netzwerk aus. Fordert ein Konnektor Ergebnisse als Stream an, kann der Tunnel Zwischenergebnisse als Server-Sent Events weiterleiten.

OpenAI-Produkte rufen den von OpenAI gehosteten Tunnelendpunkt auf. tunnel-client ruft ausstehende Anfragen per Long Polling ab und sendet die MCP-Antwort durch denselben Tunnel zurück.

Voraussetzungen

Du benötigst:

  • Eine tunnel_id aus den Tunneleinstellungen der Plattform.
  • Einen API-Schlüssel für den Betrieb von tunnel-client.
  • Einen MCP-Server, den tunnel-client aus deinem Netzwerk über stdio oder HTTP erreichen kann.

Berechtigungen und Zugriff

Die Tunnelberechtigungen der Plattform und der Zugriff auf eigene MCP-Server in ChatGPT werden getrennt verwaltet:

  • Um einen Tunnel zu erstellen oder zu bearbeiten, benötigst du für Tunnels die Berechtigungen Read + Manage.
  • Um tunnel-client auszuführen oder beim Erstellen einer App den Tunnel auszuwählen, benötigst du für Tunnels die Berechtigungen Read + Use.
  • Tunnelberechtigungen gelten für eine Plattformorganisation. Wer die Organisation besitzt oder die rollenbasierte Zugriffskontrolle (RBAC) verwaltet, kann die Tunnelrolle zuweisen.
  • Für das Hinzufügen und Verwenden eigener MCP-Server in ChatGPT gelten weiterhin die Berechtigungen und Sicherheitsbeschränkungen des Workspaces. Weitere Informationen findest du unter Eigenen MCP-Server hinzufügen.

Bitte die Administration des gewünschten ChatGPT-Workspaces um die Berechtigung, eigene MCP-Server hinzuzufügen und zu verwenden. Wende dich für die Tunnelberechtigungen an die Person, der die gewünschte Plattformorganisation gehört, oder an die RBAC-Administration dieser Organisation.

Tunnel den richtigen Organisationen und Workspaces zuordnen

Du kannst einen Tunnel einer oder mehreren Plattformorganisationen oder einem oder mehreren ChatGPT-Workspaces zuordnen. Mit diesen Zuordnungen legst du fest, in welchen OpenAI-Kontexten der Tunnel gefunden oder verwendet werden darf.

  • Ordne den Tunnel der Plattformorganisation zu, der er gehört oder die ihn verwaltet.
  • Ordne ihn dem ChatGPT-Workspace zu, in dem er beim Erstellen von Apps zur Auswahl stehen soll.
  • Füge eine weitere Plattformorganisation hinzu, wenn Codex, die Responses API oder ein anderes unterstütztes Produkt den privaten MCP-Server aus dieser Organisation aufrufen soll.
  • Verwende dieselbe tunnel_id für tunnel-client. Wenn du Organisationen oder Workspaces hinzufügst, entsteht kein zweiter Tunnel und der Endpunkt des privaten MCP-Servers bleibt gleich.

Verwende bei persönlichen Konten die persönliche Plattformorganisation des jeweiligen Kontos. Für Tests mit ChatGPT und Codex ordnest du den Tunnel dem gewünschten ChatGPT-Workspace und der Plattformorganisation zu, die Codex verwenden soll. Ein Tunnel, der ausschließlich einer persönlichen Plattformorganisation zugeordnet ist, erscheint nicht automatisch in einem Enterprise- oder Edu-Workspace.

Wenn die Plattformorganisation und der ChatGPT-Workspace bereits verknüpft sind, kannst du die fehlende Organisation oder den fehlenden Workspace in den Tunneleinstellungen der Plattform hinzufügen. Lässt sich deine Unternehmenskonfiguration nicht automatisch überprüfen, etwa weil der Plattformorganisation kein ChatGPT-Workspace entspricht, wende dich an dein OpenAI-Account-Team. Bitte das Team, die Zuordnung für das Unternehmenskonto, das den Tunnel nutzen soll, zu prüfen und manuell anzupassen.

Netzwerkanforderungen

tunnel-client benötigt keinen eingehenden Zugriff aus dem Internet. Der Client muss ausgehende HTTPS-Verbindungen zu OpenAI aufbauen und den privaten MCP-Server lokal erreichen können:

Quelle Ziel Zweck
Host mit tunnel-client api.openai.com:443 per HTTPS unter /v1/tunnel/* Standardmäßig Anfragen abrufen und Antworten senden.
Host mit tunnel-client mtls.api.openai.com:443 per HTTPS unter /v1/tunnel/* Anfragen abrufen und Antworten senden, wenn mTLS für die Steuerungsebene konfiguriert ist.
Host mit tunnel-client Konfigurierter stdio-Befehl oder URL des MCP-Servers MCP-Anfragen aus deinem Netzwerk weiterleiten.

Limits

Für das Erstellen von Tunneln und den MCP-Datenverkehr von Konnektoren gelten bei Secure MCP Tunnel standardmäßig folgende Limits:

Limit Standardwert Geltungsbereich
Anzahl der Tunnel 1.000 pro ChatGPT-Workspace und 1.000 pro Plattformorganisation Jeder Tunnel zählt für jeden zugeordneten Workspace und jede zugeordnete Plattformorganisation zum jeweiligen Limit.
MCP-Anfragerate 600 Anfragen pro Minute (dauerhaft 10 pro Sekunde) Anfragen mit derselben Tunnel-ID und derselben ID der aufrufenden Anwendung teilen sich das Limit über alle MCP-Kanäle hinweg. Ist die Anwendungs-ID nicht verfügbar, gilt das gemeinsame Limit für Anfragen derselben Person mit derselben Tunnel-ID. Mehrere tunnel-client-Prozesse erhöhen das Limit nicht.
Serialisierte Anfrage oder Antwort 10 MiB (10.485.760 Byte) Das Limit gilt für die gesamte serialisierte Tunnelnachricht einschließlich Headern und Protokollmetadaten. Für den MCP-Inhalt steht daher etwas weniger Platz zur Verfügung. Der Dienst wendet das Limit auf jede einzelne Streaming-Benachrichtigung und jede abschließende Antwort an.
Zeitlimit für Anfragen 120 Sekunden Die Frist beginnt mit dem Eingang der Anfrage in der gehosteten Warteschlange und gilt bis zur Zustellung der abschließenden Antwort. Die Wartezeit zählt mit. Fortschrittsmeldungen setzen die Frist nicht zurück.
Ausstehende Anfragen in der Warteschlange 1.000 Anfragen pro Tunnel Das Limit gilt für alle MCP-Kanäle zusammen. Es zählen nur Anfragen, die tunnel-client noch nicht abgerufen hat. Bereits zur Ausführung abgerufene Anfragen zählen nicht mit.

Diese Limits schützen den Dienst. Sie garantieren weder einen bestimmten Durchsatz noch eine bestimmte Latenz. Auch wenn Warteschlangeneinträge bis zur Bereinigung erhalten bleiben, verlängert sich die Frist von 120 Sekunden nicht. Wenn du ein höheres Limit für die Tunnelanzahl oder den Datenverkehr benötigst, wende dich an den OpenAI-Support.

tunnel-client einrichten

Öffne die Tunneleinstellungen der Plattform und verwende den dortigen Downloadlink oder lade die aktuelle öffentliche Version von tunnel-client unter openai/tunnel-client herunter. Verwende in deinem Betriebshandbuch die URL, die immer auf die neueste Version verweist, statt die URL einer bestimmten Version fest einzutragen.

Wenn dir die Binärdatei bereits vorliegt, beginne mit tunnel-client help quickstart. Für ein benanntes lokales stdio-Profil verwendest du diese Befehle:

export CONTROL_PLANE_API_KEY="sk-..."

tunnel-client init \
  --sample sample_mcp_stdio_local \
  --profile local-stdio \
  --tunnel-id tunnel_0123456789abcdef0123456789abcdef \
  --mcp-command "python /path/to/server.py"

tunnel-client doctor --profile local-stdio --explain
tunnel-client run --profile local-stdio

Für einen MCP-Server mit HTTP verwendest du --mcp-server-url https://mcp.internal.example.com/mcp anstelle von --mcp-command.

Achte darauf, dass tunnel-client run ... fehlerfrei weiterläuft, während du die App erstellst oder testest. Sowohl die App-Erkennung als auch MCP-Tool-Aufrufe benötigen den laufenden Client.

In der lokalen Verwaltungsoberfläche unter /ui siehst du vor dem Test mit ChatGPT, Codex oder einem API-Aufruf, ob der Client fehlerfrei läuft, bereit und verbunden ist.

Ausführungsort für tunnel-client wählen

Führe tunnel-client innerhalb desselben Vertrauensbereichs aus, aus dem der private MCP-Server bereits erreichbar ist. Übliche Varianten sind:

  • Kubernetes-Sidecar: Führe tunnel-client zusammen mit dem MCP-Server in einem Pod aus und stelle die Verbindung über localhost her.
  • Eigenes Kubernetes-Deployment: Führe tunnel-client separat aus, wenn der MCP-Server bereits über einen privaten Kubernetes-Service erreichbar ist.
  • VM oder systemd-Dienst: Führe tunnel-client auf einem Host aus, der den MCP-Server über ein privates Netzwerk erreichen kann.

Verbindung über ChatGPT herstellen

Öffne ChatGPT-Plugins, wähle die Plus-Schaltfläche und dann Eigenen MCP-Server hinzufügen. Wähle Tunnel unter Verbindung. Wähle einen verfügbaren Tunnel aus der Liste in ChatGPT oder füge eine gültige tunnel_id ein, wenn du bereits eine hast. Konfiguriere die Authentifizierung, lies den Risikohinweis und wähle Ich verstehe und möchte fortfahren und dann Als Plugin erstellen.

Wenn der Tunnel in ChatGPT nicht angezeigt wird, prüfe, ob er auch dem gewünschten ChatGPT-Workspace zugeordnet ist. Die Zuordnung zu einer Plattformorganisation allein reicht nicht aus. Prüfe außerdem, ob die Person, die die App erstellt, für Tunnels die Berechtigungen Read + Use hat.

Tunnel mit Codex einrichten und überprüfen

Damit Codex dich beim Setup unterstützen kann, gib Codex über den Browser Zugriff auf die Plattform und ChatGPT sowie über das Terminal Zugriff auf den Host, der deinen privaten MCP-Server erreichen kann. Füge diesen Prompt in Codex ein:

Hilf mir, mit Secure MCP Tunnel eine private Verbindung von meinem internen
MCP-Server zu ChatGPT einzurichten und von Ende zu Ende zu testen. Nutze dazu
den Browser- bzw. Computerzugriff und ein Terminal. Folge den Anleitungen unter
https://developers.openai.com/api/docs/guides/secure-mcp-tunnels und
https://github.com/openai/tunnel-client/blob/master/docs/onboarding.md und
gleiche die Schritte mit der aktuellen Benutzeroberfläche und der CLI-Hilfe ab.

Ermittle zuerst die vorgesehene Plattformorganisation und den vorgesehenen
ChatGPT-Workspace, die HTTP-URL oder den stdio-Befehl des MCP-Servers sowie
den Host für den Client. Prüfe vorhandene Tunnel, Schlüssel und eigene
MCP-Plugins in ChatGPT und verwende geeignete Ressourcen weiter. Bestätige,
dass der Tunnel der vorgesehenen Organisation und dem vorgesehenen Workspace
zugeordnet ist. Prüfe auch die Berechtigungen. Wer den Tunnel erstellt,
benötigt Tunnels Read + Manage. Der eingeschränkte API-Schlüssel für den
Betrieb und der Plugin-Operator benötigen jeweils Tunnels Read + Use.

Achte darauf, dass geheime Werte weder im Chat noch in Befehlsargumenten,
Protokollen, Screenshots oder Konfigurationsdateien erscheinen. Fordere mich
auf, die Werte lokal über eine sichere Eingabemöglichkeit einzugeben oder sie
über einen Verweis auf eine Umgebungsvariable bereitzustellen. Installiere die
unterstützte Version von tunnel-client. Führe `tunnel-client help quickstart`
aus, konfiguriere den Server und führe anschließend
`tunnel-client doctor --profile <name> --explain` aus. Starte den Client und
prüfe, ob er betriebsbereit ist und aktiv nach ausstehenden Anfragen fragt.
Lass ihn für die App-Erkennung und die Tool-Aufrufe weiterlaufen.

Füge in ChatGPT-Plugins einen eigenen privaten MCP-Server hinzu oder schließe
die bereits begonnene Einrichtung ab. Wähle unter „Verbindung“ die Option
„Tunnel“ und dann denselben Tunnel. Konfiguriere die erforderliche
Authentifizierung und führe einen sicheren, repräsentativen Tool-Aufruf aus.
Gib für jeden Prüfschritt an, woran du das Ergebnis erkannt hast. Wenn ein
Problem dich am Fortfahren hindert, nenne den genauen Fehler und den nächsten
Schritt. Melde die Einrichtung erst als abgeschlossen, wenn der Tool-Aufruf
in ChatGPT erfolgreich war.

Verbindung über die Responses API herstellen

Übergib die Tunnelkennung als tunnel_id in der MCP-Tooldefinition. Übergib den von OpenAI gehosteten Tunnelendpunkt nicht als server_url. Verwende server_url nur für einen MCP-Server, den die Responses API direkt erreichen kann.

Secure MCP Tunnel mit der Responses API verwenden
curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "input": "Use the private MCP server to answer my request.",
    "tools": [
      {
        "type": "mcp",
        "server_label": "private_mcp",
        "tunnel_id": "tunnel_0123456789abcdef0123456789abcdef"
      }
    ]
  }'

Sicherheit und Netzwerk

Der private MCP-Server bleibt in der vom Unternehmen kontrollierten Umgebung. tunnel-client verbindet sich über ausgehendes HTTPS mit OpenAI und verwendet dazu den API-Schlüssel für den Betrieb sowie bei Bedarf mTLS für die Steuerungsebene.

  • Die Adresse des MCP-Servers bleibt privat und wird ausschließlich innerhalb der Umgebung verwendet, in der tunnel-client läuft.
  • tunnel-client authentifiziert sich bei der Tunnelsteuerungsebene von OpenAI. Unterstützte OpenAI-Produkte verwenden den von OpenAI gehosteten Tunnelendpunkt.
  • Für den Tunnelzugriff gelten die bestehenden Organisations- und Workspace-Zuordnungen. Es entsteht kein separater öffentlicher Zugang.
  • tunnel-client unterstützt Netzwerkanforderungen von Unternehmen wie ausgehende Proxys, eigene CA-Zertifikatspakete, Clientzertifikate für die Steuerungsebene und mTLS auf MCP-Seite.

Was auf welcher Ebene protokolliert wird

Secure MCP Tunnel trennt den Datentransport im Tunnel von der Protokollierung auf App-Ebene:

  • Der Tunnel meldet weder die Authentifizierung bei der Steuerungsebene noch Long-Polling-Anfragen, Antworten oder einzelne Transportanfragen als App-Ereignisse an die ChatGPT Compliance Platform.
  • Änderungen an Tunnelmetadaten erscheinen in den Auditprotokollen der API-Plattform als tunnel.created, tunnel.updated und tunnel.deleted.
  • Wenn ChatGPT eine eigene App über Secure MCP Tunnel aufruft, dient der Tunnel ausschließlich dem Transport. Auf App-Ebene gilt weiterhin die übliche Compliance-Protokollierung. Dazu gehören Protokolle für App-Aufrufe und den Lebenszyklus der App-Authentifizierung, etwa APP_AUTH_LOG, wenn die App verknüpft oder die Verknüpfung aufgehoben wird.

Für Fortgeschrittene: HTTP-Aufrufe an freigegebene Ziele

Secure MCP Tunnel kann auch gezielte HTTP-Aufrufe aus unterstützten Agenten- oder API-Abläufen in ein Unternehmensnetzwerk ermöglichen. tunnel-client enthält den integrierten MCP-Server Harpoon. Er stellt konfigurierte HTTP-Ziele unter festgelegten Bezeichnungen bereit. Diese Ziele lassen sich durch den Tunnel aufrufen, wobei für Anfragen und Antworten feste Limits gelten.

Nutze Harpoon, wenn du eine kleine Anzahl privater REST-Endpunkte erreichen möchtest, ohne sie öffentlich zugänglich zu machen. Harpoon ist kein universeller Proxy. Beim Aufruf lässt sich der Host nicht frei wählen. Zulässig sind ausschließlich die vom Unternehmen konfigurierten Ziele und Methoden.

Fehlerbehebung

  • „Tunnels access required“ in den Tunneleinstellungen der Plattform: Tunnelberechtigungen gelten auf Organisationsebene, nicht auf Projektebene. Wähle die gewünschte Plattformorganisation. Bitte dann die Person, der die Organisation gehört, oder die RBAC-Administration, dir eine passende Rolle zuzuweisen oder dich in eine passende Gruppe aufzunehmen. Mit Read kannst du Tunnel anzeigen. Mit Read + Manage kannst du sie erstellen, bearbeiten oder löschen. Falls keine passende Rolle existiert, kann die zuständige Person eine Rolle erstellen, sie einer Gruppe zuweisen und dich in die Gruppe aufnehmen. Du benötigst außerdem Use, um tunnel-client auszuführen oder in den Konnektoreinstellungen einen Tunnel auszuwählen. Es kann bis zu 30 Minuten dauern, bis eine neue Rollenzuweisung wirksam wird.
  • Tunnel in ChatGPT nicht sichtbar: Prüfe, ob der Tunnel neben der Plattformorganisation auch dem gewünschten ChatGPT-Workspace zugeordnet ist. Prüfe anschließend, ob der Konnektor-Operator für Tunnels die Berechtigung Use hat. Lässt sich der Workspace bei einem Unternehmenskonto nicht automatisch verknüpfen, bitte dein OpenAI-Account-Team, die Zuordnung zu prüfen und manuell anzupassen.
  • Konnektorerkennung oder Tool-Aufrufe schlagen fehl: Prüfe, ob tunnel-client run ... weiterhin läuft, und führe dann tunnel-client doctor --profile <name> --explain erneut aus.
  • Du kannst einen Tunnel anzeigen, aber nicht bearbeiten: Vermutlich hast du für Tunnels die Berechtigung Read, aber nicht Manage.
  • tunnel-client stellt /healthz, /readyz, /metrics und eine lokale Verwaltungsoberfläche unter /ui bereit.
  • Die Verwaltungsoberfläche ist standardmäßig nur über die Loopback-Schnittstelle erreichbar. Mache sie nur dann aus der Ferne zugänglich, wenn der Zugriff aus einem Betriebsnetz ausdrücklich erforderlich ist.
  • Prüfe über diese Schnittstellen, ob der Client fehlerfrei läuft, bereit ist und aktiv Anfragen abruft, bevor du ihn mit ChatGPT, Codex oder einem API-Aufruf testest.
  • Ist der Client nicht verbunden, schlagen Anfragen durch den Tunnel fehl, bis tunnel-client die Verbindung wiederherstellt.
  • Die Protokollierung von HTTP-Rohdaten ist standardmäßig deaktiviert. In Exporten für den Support werden sensible Angaben unkenntlich gemacht.

OAuth

  • Die OAuth-Discovery kann über den Tunnel erfolgen, sodass der MCP-Server selbst privat bleiben kann.
  • Der Tunnel erhält die Metadaten des vorgelagerten Autorisierungsservers, die für OAuth-Abläufe im Browser erforderlich sind.
  • Der Autorisierungsserver selbst ist nicht automatisch über den Tunnel erreichbar. Ist er weder aus dem öffentlichen Internet noch vom Host mit tunnel-client erreichbar, kann der OAuth-Ablauf auch dann fehlschlagen, wenn der MCP-Server erreichbar ist.

Wo du den Tunnel konfigurierst

Nächste Schritte

  • Erstelle oder verwalte den Tunnel in den Tunneleinstellungen der Plattform.
  • Prüfe dein Profil für tunnel-client mit tunnel-client doctor --profile <profile> --explain.
  • Stelle über ChatGPT-Plugins oder die von dir verwendete unterstützte OpenAI-Oberfläche eine Verbindung zum Tunnel her.
Screenshot der Tunneleinstellungen auf der OpenAI-Plattform mit unkenntlich gemachten sensiblen Angaben.

In den Tunneleinstellungen der Plattform kannst du von OpenAI gehostete MCP-Tunnelendpunkte erstellen und verwalten.