Mit dem Model Context Protocol (MCP) können ChatGPT und Codex Tools und Informationen aus anderen Systemen nutzen. Ein MCP-Server beschreibt die verfügbaren Tools und verarbeitet Anfragen, etwa um ein Ticket nachzuschlagen oder Dokumentation abzurufen.
Wähle den passenden Einstieg für deine Aufgabe:
- Neue Verbindung einrichten: Erstelle mit Plugin Creator und Sites ein Plugin für das System deines Teams.
- Vorhandenen Server nutzen: Verbinde ihn mit ChatGPT oder Codex. Dafür gibt es Anleitungen für Web, Desktop, CLI und IDE.
Beispiel: Ein Ticket im Supportsystem deines Teams nachschlagen.
Ein Plugin stellt eine MCP-Verbindung für ChatGPT bereit. Plugins können auch Skills mit wiederverwendbaren Anweisungen enthalten. Wenn du nur Anweisungen brauchst, lies Plugins erstellen.
Ein MCP-Plugin mit Plugin Creator und Sites erstellen
Mit Plugin Creator erstellst und bearbeitest du dein Plugin. Auf Sites hostest du den zugehörigen MCP-Server.
Bevor du beginnst
Schau zuerst im Plugin-Verzeichnis nach. Wenn du eine neue Verbindung brauchst, besorge dir die API-Dokumentation deines Systems und kläre, wie du die Verbindung herstellen darfst. Wenn du Hilfe brauchst, frag die für das System verantwortliche Person.
Im folgenden Beispiel erstellst du das Plugin Support Ticket Lookup. Ersetze [ticketing system] durch den Namen deines Systems.
Nutzt du ChatGPT Enterprise?
Bitte die Person, der dein Workspace gehört oder die ihn verwaltet, unter Workspace-Einstellungen → Berechtigungen und Rollen Folgendes zu prüfen:
- Plugins verwenden erlaubt das Erstellen, Bearbeiten und Verwenden von Plugins. Zum Bearbeiten brauchst du außerdem Bearbeitungsrechte für das jeweilige Plugin.
- Zugriff auf Sites brauchst du, um deine Site zu erstellen und zu veröffentlichen.
- Plugins hochladen und Plugins mit MCPs erstellen braucht die Person, der die Site gehört und die das MCP-Plugin veröffentlicht.
Plugins verwenden ist standardmäßig aktiviert. Die beiden Berechtigungen zum Veröffentlichen von MCP-Plugins sind standardmäßig deaktiviert. Weitere Informationen findest du unter Zugriff auf Sites und Plugin-Berechtigungen.
1. Plugin erstellen
Starte eine neue Aufgabe in Work, wähle @Plugin Creator aus und füge deine API-Dokumentation als Anhang hinzu. Beschreibe die Aufgabe:
Du klärst noch den API-Zugriff? Bitte Plugin Creator, vorerst Beispieldaten zu verwenden.
2. Dein System verbinden
Bitte Plugin Creator in derselben Unterhaltung, den Server mit der API deines Systems zu verbinden und dich durch die Anmeldung zu führen. Verwende die von deiner Organisation genehmigte Authentifizierungsmethode. Gib keine Passwörter, API-Schlüssel oder anderen Geheimnisse in den Chat ein.
Du brauchst Hilfe? Schick die Unterhaltung mit Plugin Creator und die API-Dokumentation an die für das System verantwortliche Person oder an jemanden aus der Entwicklung. Bitte um Hilfe beim Einrichten des Zugriffs.
Details zur Verbindung und zum Hosting
Sites übernimmt die Anmeldung zwischen ChatGPT und deinem MCP-Server. Dein Server braucht weiterhin eine genehmigte Verbindung zur API deines Systems. Die API legt fest, auf welche Datensätze und Aktionen der Server zugreifen kann.
Wenn du einen anderen Host verwendest, folge zuerst der Anleitung Einen MCP-Server erstellen und anschließend der Anleitung Dein Plugin verbinden und testen. Wie du die Anmeldung einrichtest, erfährst du im Leitfaden zur Authentifizierung.
3. Veröffentlichen und installieren
Bitte Plugin Creator, den Server über Sites mit deinen aktuellen Zugriffseinstellungen zu veröffentlichen und dir den Link zum Plugin zu geben. Damit das Plugin entsteht, muss die Person, der die Site gehört, sie veröffentlichen. Wenn du nur Bearbeitungsrechte hast, bitte diese Person darum.
- Öffne die Plugin-Karte. Du findest sie auch unter Plugins → Persönlich → Von dir erstellt.
- Wähle Installieren und dann Verbinden. Melde dich an, wenn du dazu aufgefordert wirst.
4. Dein Plugin verwenden
Starte eine neue Aufgabe in Work, wähle dein Plugin mit @ aus und frag „Welchen Status hat Ticket 123?“. Verwende dabei eine Ticketnummer aus deinem System. Du kannst die Tools des Plugins zusammen mit anderen Plugins in derselben Unterhaltung nutzen.
Dein Plugin teilen oder bearbeiten
In Business oder Enterprise kannst du Teammitglieder über die Freigabeeinstellungen des Plugins einladen. Dafür brauchst du die Berechtigung Plugins teilen. Für die Aufnahme in das Workspace-Verzeichnis brauchst du zusätzlich Plugins im Workspace veröffentlichen. Weitere Informationen findest du unter Freigabeberechtigungen.
Teammitglieder brauchen Zugriff auf das Plugin, die zugehörige App und die Site (mindestens Leserechte). Jede Person installiert das Plugin und stellt die Verbindung mit ihrem eigenen Konto her. Welche Datensätze zugänglich sind, hängt von der API-Verbindung des Servers ab.
Um dieses auf Sites gehostete Plugin zu bearbeiten, öffne wieder deine Unterhaltung mit Plugin Creator, bitte um die Aktualisierung der bestehenden Site und veröffentliche die Änderungen. Bei anderen bearbeitbaren Plugins wählst du Plugin bearbeiten, um eine Unterhaltung mit Plugin Creator zur Bearbeitung zu starten. Mehr dazu unter Ein vorhandenes Plugin bearbeiten.
Eine benutzerdefinierte GPT-Aktion ersetzen
Schritte zur GPT-Migration anzeigen
Benutzerdefinierte GPT-Aktionen werden bei der Migration nicht in Plugins übernommen. Erstelle die Verbindung als neues Sites-Plugin und verwende nach Möglichkeit die vorhandene API.
Beim Veröffentlichen erstellt Sites ein separates Plugin. Dein migriertes Plugin erhält die Verbindung nicht. Du kannst beide Plugins in derselben Unterhaltung verwenden. Skills und Referenzdateien lassen sich in Sites-Plugins derzeit nicht bearbeiten.
1. Den ursprünglichen GPT um einen Prompt zum Nachbilden des Workflows bitten
Öffne den ursprünglichen GPT und gib folgenden Prompt ein:
2. Den Prompt mit den Aktionseinstellungen abgleichen
Sichere vor der Migration das Aktionsschema, die Authentifizierungsmethode und die nicht vertraulichen Verbindungseinstellungen aus dem Abschnitt „Aktionen“ im GPT-Editor. Ergänze damit fehlende Angaben im Prompt oder bitte die Person, der der GPT gehört, um Hilfe.
3. Ein neues Sites-Plugin erstellen
Starte eine neue Aufgabe. Wähle in Work @Plugin Creator aus. In Codex verwendest du $plugin-creator. Füge den geprüften Prompt ein und hänge das Schema oder die API-Dokumentation an. Bitte darum, den Server auf Sites zu hosten.
Folge den Anleitungen Dein System verbinden und Veröffentlichen und installieren. Wähle dann das neue Plugin in einer Work-Aufgabe aus und bitte es, deine ursprüngliche Aufgabe auszuführen. Weitere Informationen findest du in den FAQ zur Migration.
Fehlerbehebung
Wenn das Plugin nicht wie erwartet funktioniert
Wenn ein Verbindungsfehler auftritt oder Tools fehlen, prüfe, ob die Person, der die Site gehört, die neueste Version veröffentlicht hat und ob das Plugin installiert und verbunden ist. Gib die Fehlermeldung an Plugin Creator oder die für den Server verantwortliche Person weiter.
Wenn ChatGPT das Tool nicht verwendet, wähle das Plugin mit @ aus und bitte um eine konkrete Abfrage. Wenn ein Teammitglied das Plugin nicht nutzen kann, prüfe dessen Zugriffsrechte für das Plugin, die App, die Site und die Datensätze.
Ist das Plugin als Nur Desktop gekennzeichnet, verwende eine unterstützte Desktop-App oder bitte die Person, die es erstellt hat, zu prüfen, wie das Plugin gepackt ist. Ein Remote-MCP-Server allein reicht für die Nutzung im Web nicht aus.
Einen vorhandenen MCP-Server verbinden
ChatGPT nutzt im Web Plugins für den Zugriff auf Remote-MCP-Tools. Wenn du bereits einen Server hast, folge der Anleitung Dein Plugin verbinden und testen. Lokale Codex-Clients können sich auch direkt mit MCP-Servern verbinden und dieselbe Konfiguration verwenden.
Wähle die Oberfläche, die du verwendest, um die passenden Setup- und Konfigurationsoptionen zu sehen.
Die ChatGPT-Desktop-App, die Codex CLI und die IDE-Erweiterung unterstützen MCP-Server. Auf demselben Codex-Host verwenden sie dieselbe MCP-Konfiguration.
Die folgenden Funktionen gelten für MCP-Server, die auf einem Codex-Host konfiguriert sind. Gehostete Plugin-Tools können andere Funktionen bieten.
Unterstützte MCP-Funktionen
- STDIO-Server: Server, die als lokaler Prozess laufen und mit einem Befehl gestartet werden.
- Umgebungsvariablen
- Streamable-HTTP-Server: Server, auf die du über eine Adresse zugreifst.
- Authentifizierung mit Bearer-Token
- OAuth-Authentifizierung einschließlich Client ID Metadata Documents (CIMD) und Dynamic Client Registration (DCR)
- Authentifizierung über die ChatGPT-Sitzung für vertrauenswürdige Server von OpenAI
- Serveranweisungen: Codex liest bei der Initialisierung das vom Server zurückgegebene MCP-Feld
instructionsund berücksichtigt dessen Anweisungen bei der Nutzung aller Tools dieses Servers.
Wenn du einen MCP-Server für Codex entwickelst oder betreust, verwende instructions für Workflows, die mehrere Tools nutzen, sowie für serverweit geltende Einschränkungen und Ratenlimits. Formuliere die ersten 512 Zeichen so, dass sie für sich verständlich sind. So stehen Codex die wichtigsten Anweisungen zur Verfügung, wenn es entscheidet, wie es den Server nutzt.
Codex mit einem MCP-Server verbinden
Codex speichert die MCP-Konfiguration zusammen mit den übrigen Codex-Einstellungen in config.toml. Standardmäßig ist das die Datei ~/.codex/config.toml. Mit .codex/config.toml kannst du MCP-Server auch für ein einzelnes Projekt konfigurieren. Das ist nur bei vertrauenswürdigen Projekten möglich.
Die ChatGPT-Desktop-App, die Codex CLI und die IDE-Erweiterung verwenden dieselbe Konfiguration. Sobald du deine MCP-Server konfiguriert hast, kannst du zwischen diesen Clients wechseln, ohne das Setup zu wiederholen.
MCP in der ChatGPT-Desktop-App konfigurieren
- Öffne Einstellungen und wähle MCP-Server aus.
- Wähle Server hinzufügen aus.
- Gib einen Namen ein, wähle STDIO oder Streamable HTTP aus und gib den Startbefehl oder die URL des Servers an.
- Speichere den Server und wähle Neu starten aus.
Die Serverliste zeigt, welche Server aktiviert sind und welche OAuth erfordern. Wähle Authentifizieren aus, wenn ein OAuth-Server eine Anmeldung verlangt. Gib im Editor /mcp ein, um die verbundenen Server anzuzeigen.
MCP-Tools in ChatGPT im Web verwenden
Wenn du eine Unterhaltung mit lokalem Computerzugriff über Work Cloud auf einem anderen Gerät fortsetzt, werden dadurch weder Plugins installiert noch Zugriffsrechte für verbundene Konten erteilt.
Beim lokalen Computerzugriff über Work Cloud gilt die TOML-Vorgabe mcp_servers für Unternehmen in Agent Security für lokale Ausführungsumgebungen. Für Cloud-Container gelten weiterhin die Richtlinien von Work Cloud. Lokale MCP-Server und Transportverfahren sind in der Cloud möglicherweise nicht verfügbar. Prüfe die Verbindung und die Authentifizierung separat.
Für Enterprise-Hooks beim lokalen Computerzugriff über Work Cloud gilt Folgendes:
- Enterprise-Hooks. Wenn die Funktion für deinen Workspace aktiviert ist, unterstützt der lokale Computerzugriff über Work Cloud administrativ festgelegte MCP-Hooks. Diese laufen bei unterstützten Lebenszyklus- und Tool-Ereignissen auf dem Cloud-Koordinator (Orchestrator). Bei der Orchestrierung in der Cloud werden Befehls-Hooks und Hooks aus der lokalen Konfiguration oder aus Plugins nicht unterstützt, auch wenn die Tools lokal ausgeführt werden.
- Auditierung. Bevor du dich auf diese Hooks verlässt, teste die Callback-Verbindung, prüfe, welche Ereignisse sie empfängt, und kläre, wie sich Fehler auf die Aufgabe auswirken. MCP-Hooks liefern kein vollständiges Audit-Protokoll für die Compliance API.
- Einschränkungen: Bei der Orchestrierung in der Cloud werden Befehls-Hooks und Hooks aus der lokalen Konfiguration oder aus Plugins nicht unterstützt, auch wenn die Tools lokal ausgeführt werden. Für Privatkonten unterstützt diese Funktion keine Hooks. Wenn sowohl die Orchestrierung als auch die Ausführung lokal erfolgen, funktionieren bereits unterstützte Hooks weiterhin in rein lokalen Work- und Codex-Threads. Für diese Workflows lassen sich unterstützte verwaltete Hooks weiterhin in Agent Security administrativ konfigurieren.
Welche Funktionen unterstützt werden, erfährst du unter Hooks und in der Konfigurationsreferenz.
Installiere in einem gehosteten Chat in ChatGPT Work ein Plugin, um dessen Konnektoren und Remote-MCP-Tools zu nutzen. Nach der Installation können Chat und Work diese Tools verwenden. Wer den Workspace verwaltet, kann festlegen, welche Plugins und Tools verfügbar sind.
ChatGPT im Web liest keine lokalen Codex-Konfigurationsdateien und bietet keinen Zugriff auf das lokale Codex-Befehlsmenü. Öffne den Tab Plugins, um die verfügbaren Tools zu durchsuchen und zu verwalten.
MCP mit der CLI konfigurieren
Einen MCP-Server hinzufügen
codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>Um beispielsweise Context7 hinzuzufügen, einen kostenlosen MCP-Server für Entwicklungsdokumentation, kannst du diesen Befehl ausführen:
codex mcp add context7 -- npx -y @upstash/context7-mcpWeitere CLI-Befehle
Führe codex mcp list aus, um die konfigurierten Server anzuzeigen. Mit codex mcp --help zeigst du alle verfügbaren MCP-Befehle an. Wenn ein Server OAuth unterstützt, führe codex mcp login <server-name> aus. Wenn du ein Terminal ohne lokalen Browser verwendest, führe codex mcp login <server-name> --no-browser aus. Öffne die ausgegebene Autorisierungs-URL in einem Browser und melde dich an. Kopiere anschließend die vollständige Weiterleitungs-URL und füge sie im Terminal ein, auch wenn der Browser die Callback-Seite nicht laden kann.
Terminal-Oberfläche (TUI)
In der TUI von codex zeigst du mit /mcp deine aktiven MCP-Server an.
MCP in der IDE-Erweiterung konfigurieren
- Öffne das Zahnradmenü und wähle MCP-Server aus.
- Wähle Server hinzufügen aus.
- Gib einen Namen ein, wähle STDIO oder Streamable HTTP aus und gib den Startbefehl oder die URL des Servers an.
- Speichere den Server und wähle Erweiterung neu starten aus.
Die Liste der MCP-Server zeigt, welche Server aktiviert sind und welche OAuth erfordern. Wähle Authentifizieren aus, wenn ein OAuth-Server eine Anmeldung verlangt.
MCP mit config.toml konfigurieren
Für detailliertere Einstellungen bearbeite ~/.codex/config.toml oder die projektspezifische Datei .codex/config.toml. In der Konfigurationsreferenz findest du eine durchsuchbare Liste aller unterstützten MCP-Optionen.
Lege für jeden MCP-Server eine Tabelle [mcp_servers.<server-name>] in der Konfigurationsdatei an.
STDIO-Server
command(erforderlich): Befehl, der den Server startet.args(optional): Argumente, die an den Server übergeben werden.env(optional): Umgebungsvariablen, die für den Server gesetzt werden.env_vars(optional): Umgebungsvariablen, die zugelassen und weitergegeben werden.cwd(optional): Arbeitsverzeichnis, aus dem der Server startet.
env_vars kann einfache Variablennamen oder Objekte mit Quellenangabe enthalten:
env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]Bei Zeichenketten und bei source = "local" liest Codex die Werte aus seiner lokalen Umgebung. Bei source = "remote" liest Codex sie aus der Remote-Ausführungsumgebung. Dafür ist MCP über stdio in der Remote-Umgebung erforderlich.
Streamable-HTTP-Server
url(erforderlich): Adresse des Servers.auth(optional): Authentifizierungsmethode, die Codex nach den konfigurierten Bearer-Token und Autorisierungsheadern versucht. Mitoauth(Standard) verwendet Codex gespeicherte MCP-OAuth-Zugangsdaten. Mitchatgptverwendet Codex für den vertrauenswürdigen ChatGPT-Origin von OpenAI die aktuelle ChatGPT-Sitzung und greift bei Bedarf auf gespeicherte OAuth-Zugangsdaten zurück.bearer_token_env_var(optional): Name der Umgebungsvariablen mit dem Bearer-Token, das inAuthorizationgesendet wird.http_headers(optional): Zuordnung von Headernamen zu statischen Werten.env_http_headers(optional): Zuordnung von Headernamen zu Namen von Umgebungsvariablen. Die Werte stammen aus der Umgebung.http_headers_helper(optional): Lokaler Befehl, der ein JSON-Objekt mit Headernamen und Zeichenkettenwerten ausgibt, etwa{"X-Auth": "temporary-token"}. Diese Option wird für MCP-Verbindungen über HTTP aus der lokalen Umgebung unterstützt. Für stdio-Server oder Verbindungen über eine Remote-Ausführungsumgebung steht sie nicht zur Verfügung.
Codex speichert die vom Hilfsbefehl gelieferten Header für die Verbindung zwischen. Gibt eine POST-Anfrage an denselben Origin 401 oder 403 zurück, ruft Codex die Header einmal neu ab. Es wiederholt die Anfrage nur, wenn der Hilfsbefehl geänderte Werte liefert. Explizite Bearer-Token und OAuth-Zugangsdaten haben Vorrang vor einem vom Hilfsbefehl gelieferten Authorization-Header. Meldet eine OAuth-Antwort mit Status 403 einen unzureichenden Berechtigungsumfang, ruft Codex die Header nicht neu ab.
Liefert keine der Quellen Zugangsdaten, kann Codex ohne Authentifizierung eine Verbindung zum Server herstellen. Führe codex mcp login <server-name> separat aus, um die OAuth-Anmeldung für MCP zu starten.
Weitere Konfigurationsoptionen
- Mit
environment_idwählst du die Umgebung für einen stdio- oder Streamable-HTTP-Server. Der Standardwert istlocal. Für eine Verbindung über eine Remote-Ausführungsumgebung gib deren registrierte Umgebungs-ID an. startup_timeout_sec(optional): Zeitlimit in Sekunden für den Serverstart. Standard:10.tool_timeout_sec(optional): Zeitlimit in Sekunden für die Ausführung eines Tools durch den Server. Standard:60.enabled(optional): Mitfalsedeaktivierst du den Server, ohne ihn zu löschen.- Setze
required = true, damit Codex den Start abbricht, wenn dieser aktivierte Server nicht bereit ist. Die Standardeinstellungstartup_readiness = "connection"erfordert eine aktive Verbindung. Mitstartup_readiness = "catalog"genügt für den Start ein gültiger zwischengespeicherter Tool-Katalog, während die Verbindung zum Server aufgebaut wird. Tool-Aufrufe erfordern weiterhin eine aktive Verbindung. enabled_tools(optional): Liste der erlaubten Tools.disabled_tools(optional): Liste der gesperrten Tools. Sie wird nachenabled_toolsangewendet.default_tools_approval_mode(optional): Legt fest, wann für Tools dieses Servers standardmäßig eine Genehmigung nötig ist. Unterstützt werdenauto,prompt,writesundapprove. Im Moduswritesfragt Codex nach einer Genehmigung, wenn ein Tool nicht als Tool ohne Schreibzugriff gekennzeichnet ist.tools.<tool>.approval_mode(optional): Überschreibt die Genehmigungseinstellung für ein einzelnes Tool.tools.<tool>.output_token_limit(optional): Positives Token-Budget für die Ausgabe eines Tools, bevor der übliche Zuschlag von 20 % für die Serialisierung hinzukommt. Überschreibt die Standardgrenze des Modells, ab der die Ausgabe dieses Tools gekürzt wird.
Die Einstellung mcp_optional_startup_grace_ms auf der obersten Ebene legt fest, wie lange Codex beim Erstellen des anfänglichen Tool-Katalogs auf optionale MCP-Server wartet. Der Standardwert beträgt 1000 Millisekunden. Setze den Wert auf 0, damit Codex stattdessen für jeden Server dessen startup_timeout_sec berücksichtigt. Für erforderliche Server gelten weiterhin ihre jeweiligen Startzeitlimits.
OAuth-Clientregistrierung und Callbacks
Wenn dein Autorisierungsserver einen vorab registrierten OAuth-Client verlangt, gib beim Hinzufügen des MCP-Servers die Client-ID an:
codex mcp add example --url https://mcp.example.com --oauth-client-id my-clientBei einem vertraulichen Client gib zusätzlich --oauth-client-secret an. Lies das Client-Secret aus einer Umgebungsvariablen:
codex mcp add example --url https://mcp.example.com --oauth-client-id my-client --oauth-client-secret "$MCP_CLIENT_SECRET"Diese Option erfordert eine Client-ID und ein Client-Secret, die beide nicht leer sein dürfen. Codex speichert das Secret als mcp_servers.example.oauth.client_secret in config.toml. Halte die Datei privat und nimm sie nicht in die Versionsverwaltung auf.
Registriere genau die Callback-URL, die codex mcp add ausgibt. Wenn der Autorisierungsserver Unterstützung für die Ausstellerkennung meldet, kann die CLI folgende URL ausgeben:
OAuth callback URL: http://127.0.0.1/callbackFür den öffentlichen Client in diesem Beispiel speichert Codex die Callback-URL und die Client-ID in config.toml für spätere Anmeldungen:
[mcp_servers.example]
url = "https://mcp.example.com"
[mcp_servers.example.oauth]
client_id = "my-client"
callback_url = "http://127.0.0.1/callback"Neu hinzugefügte, vorab registrierte Clients verwenden nur dann eine stabile Callback-URL, wenn der Autorisierungsserver authorization_response_iss_parameter_supported: true meldet und in seinen Metadaten einen issuer angibt. Meldet er keine Unterstützung für die Ausstellerkennung, hängt Codex eine serverspezifische Callback-ID an die URL an, beispielsweise http://127.0.0.1/callback/XuuuHAzzHOni. Bestehende Clients ohne gespeicherte Callback-URL verwenden weiterhin ihre Weiterleitung mit Callback-ID.
Welchen Callback Codex bei der Anmeldung verwendet, hängt von der OAuth-Konfiguration und den Metadaten des Autorisierungsservers ab:
| OAuth-Konfiguration | Unterstützung der Ausstellerkennung | Verwendeter Callback |
|---|---|---|
callback_url ohne client_id |
Unterstützt | Codex verwendet die konfigurierte Callback-URL für die Clientregistrierung. |
callback_url ohne client_id |
Nicht unterstützt | Codex hängt die serverspezifische Callback-ID an die konfigurierte Callback-URL an und verwendet diese URL für die Clientregistrierung. |
client_id und callback_url |
Unterstützt | Codex verwendet die konfigurierte Callback-URL erneut. Die Autorisierungsantwort muss den passenden iss-Wert enthalten. |
client_id und eine callback_url, die mit der richtigen Callback-ID endet |
Nicht unterstützt | Codex verwendet die konfigurierte Callback-URL unverändert. |
client_id und eine callback_url ohne die richtige Callback-ID |
Nicht unterstützt | Codex ignoriert die konfigurierte Callback-URL. Es verwendet mcp_oauth_callback_url oder, falls nicht gesetzt, http://127.0.0.1/callback und hängt die Callback-ID an. |
client_id ohne konfigurierte callback_url |
Unterstützt oder nicht unterstützt | Codex verwendet die globale Callback-URL oder die Standard-Callback-URL und hängt die serverspezifische Callback-ID an. |
Die gespeicherte Callback-URL bleibt beim Rückgriff auf eine andere URL unverändert. Codex leitet die Callback-ID aus der URL des MCP-Servers einschließlich Pfad und Abfragezeichenfolge ab. Für die automatische und die explizite Anmeldung gelten dieselben Auswahlregeln.
Setze mcp_oauth_callback_url, wenn du einen eigenen Callback-Pfad oder die Ingress-URL einer Remote-Devbox brauchst. Neu hinzugefügte, vorab registrierte Clients verwenden diese URL unverändert, wenn ihr Anbieter die Ausstellerkennung unterstützt. Andernfalls hängen sie die serverspezifische Callback-ID an die konfigurierte URL an. Registriere immer genau die Callback-URL, die codex mcp add anzeigt.
Bei Callbacks über http://127.0.0.1 ohne expliziten Port lässt Codex den Listener-Port in der angezeigten und gespeicherten URL weg. Erst bei der Autorisierung fügt Codex den aktiven Listener-Port ein. Das gilt nicht für localhost, IPv6-Hosts, HTTPS-URLs oder Callbacks, die bereits einen Port enthalten. Autorisierungsserver müssen gemäß RFC 8252, Abschnitt 7.3 variable Loopback-Ports akzeptieren.
Mit mcp_oauth_callback_port legst du einen festen globalen Listener-Port fest. Mit mcp_servers.<server-name>.oauth.callback_port überschreibst du ihn für einen einzelnen Server. Ein expliziter Port in der Callback-URL konfiguriert den Listener nicht. Verwende für einen direkten Loopback-Callback http://127.0.0.1 ohne expliziten Port oder gib für Callback-URL und Listener denselben Port an. Bei einem Callback über einen Proxy darf der Port der externen URL bewusst vom lokalen Listener-Port abweichen. Bei lokalen Callback-URLs bindet Codex den Listener an die lokale Netzwerkschnittstelle, bei nicht lokalen Callback-URLs an 0.0.0.0.
Codex prüft jeden zurückgegebenen iss-Wert, bevor es den Autorisierungscode eintauscht. Stimmt iss nicht überein, weist Codex die Antwort immer zurück. Meldet der Server Unterstützung für die Ausstellerkennung, weist Codex auch Antworten ohne iss zurück. In beiden Fällen tauscht Codex den Code nicht ein und weicht auch nicht auf einen anderen Callback aus. Eine fehlerhafte Callback-URL oder die gemeldete Unterstützung der Ausstellerkennung ohne Ausstellerangabe in den Metadaten führt ebenfalls zum Abbruch. Mehr dazu unter Personen authentifizieren.
Setze mcp_servers.<server-name>.scopes in config.toml, um die OAuth-Scopes für einen Server festzulegen. Mit codex mcp login <name> --scopes read,write überschreibst du sie für eine einzelne Anmeldung. Wenn du keine der beiden Optionen angibst, fordert Codex die Scopes aus der ersten WWW-Authenticate-Challenge des Servers an. Enthält die Challenge keine Scopes, verwendet Codex die Scopes aus den Metadaten der geschützten Ressource, sofern dort welche angegeben sind.
Bei einer leeren Liste (scopes = []) kann die OAuth-Bibliothek die Scopes weiterhin selbst auswählen. Sie kann auch offline_access hinzufügen, wenn der Autorisierungsserver dies unterstützt.
OAuth-Clientregistrierung
Codex unterstützt OAuth Client ID Metadata Documents (CIMD) und Dynamic Client Registration (DCR). Standardmäßig wählt Codex automatisch CIMD, wenn der Autorisierungsserver client_id_metadata_document_supported: true meldet, none in token_endpoint_auth_methods_supported aufführt und der Callback eine unterstützte Loopback-URL verwendet. Andernfalls verwendet Codex DCR, sofern verfügbar. Eine konfigurierte OAuth-Client-ID hat immer Vorrang. In diesem Fall überspringt Codex die Clientregistrierung.
Bei CIMD ohne an den Aussteller gebundene Antworten verwendet die Codex CLI ein von ChatGPT gehostetes Metadatendokument für den jeweiligen MCP-Server:
https://chatgpt.com/oauth/codex/<callback_id>/client.jsonCodex leitet <callback_id> aus der URL des MCP-Servers ab und fügt die ID in den Loopback-Weiterleitungs-URI ein, etwa http://127.0.0.1:<port>/callback/<callback_id>. Das Metadatendokument registriert den zugehörigen Loopback-URI ohne Port. Autorisierungsserver müssen den bei der Anmeldung gewählten Port akzeptieren und prüfen, ob Host und Pfad exakt übereinstimmen. Das schreibt RFC 8252 vor. Für benutzerdefinierte Callback-Hosts, Pfade oder Abfrageparameter brauchst du DCR oder eine konfigurierte OAuth-Client-ID.
Die Codex CLI unterstützt auch ein stabiles, gemeinsam genutztes CIMD-Dokument:
https://chatgpt.com/oauth/codex/client.jsonDie Codex CLI verwendet das stabile Dokument mit dem gemeinsamen Pfad /callback, wenn der Autorisierungsserver authorization_response_iss_parameter_supported: true meldet, in seinen Metadaten einen gültigen issuer angibt und in Autorisierungsantworten den passenden iss-Wert zurückgibt. Server ohne an den Aussteller gebundene Antworten verwenden das Callback-spezifische Dokument.
Um die Registrierungsmethode für eine einzelne CLI-Anmeldung auszuwählen, verwende --oauth-client-registration:
codex mcp login <server-name> --oauth-client-registration cimd
codex mcp login <server-name> --oauth-client-registration dcrDer Standardwert ist auto. Die gewählte Registrierungsmethode gilt nur für die aktuelle Anmeldung. Codex speichert sie nicht in config.toml.
Beispiele für config.toml
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]
[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"# Optional MCP OAuth callback overrides (used by `codex mcp login`)
mcp_oauth_callback_port = 5555
mcp_oauth_callback_url = "https://devbox.example.internal/callback"[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"] # applied after enabled_tools
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true
[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"
output_token_limit = 30000MCP-Server aus Plugins
Installierte Plugins können MCP-Server in ihrem Manifest mitliefern. Das Plugin startet diese Server. Der Befehl für den Transport wird deshalb nicht in deiner persönlichen Konfiguration festgelegt. Unter plugins.<plugin>.mcp_servers.<server> kannst du den Server weiterhin aktivieren oder deaktivieren und Regeln für seine Tools festlegen.
[plugins."sample@test".mcp_servers.sample]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["read", "search"]
[plugins."sample@test".mcp_servers.sample.tools.search]
approval_mode = "approve"Plugins können für ihre HTTP-MCP-Server auch OAuth-Einstellungen in .mcp.json angeben. Plugin-Manifeste verwenden dafür die Feldnamen clientId, callbackUrl und callbackPort in camelCase:
{
"mcpServers": {
"sample": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"oauth": {
"clientId": "my-pre-registered-client",
"callbackUrl": "http://127.0.0.1/callback/registered"
}
}
}
}Für MCP-Server aus Plugins gelten dieselben Regeln zur Auswahl des Callbacks wie für andere MCP-Server. Wenn ein Plugin eine clientId angibt, sein Anbieter keine an den Aussteller gebundenen Callbacks unterstützt und in callbackUrl die serverspezifische Callback-ID fehlt, ignoriert Codex diese URL bei der Anmeldung. Codex verwendet dann mcp_oauth_callback_url oder, falls nicht gesetzt, http://127.0.0.1/callback und hängt die Callback-ID an. Der konfigurierte Wert von callbackUrl bleibt unverändert.
Der Plugin-Wert oauth.callbackPort hat Vorrang vor dem globalen Wert mcp_oauth_callback_port. Ist keiner der beiden Werte gesetzt, wählt Codex einen temporären Port. Der in callbackUrl angegebene Port legt den Listener-Port nicht fest. Konfiguriere für einen direkten Loopback-Callback mit festem Port beide Werte so, dass die Ports übereinstimmen:
{
"callbackUrl": "http://127.0.0.1:4321/callback/registered",
"callbackPort": 4321
}Bei einem Remote-Ingress oder einem anderen Proxy dürfen der Port in der Callback-URL und der lokale Listener-Port bewusst voneinander abweichen, wenn der Proxy Anfragen an den konfigurierten Listener weiterleitet.
Beispiele für nützliche MCP-Server
Die Zahl der MCP-Server wächst. Hier findest du einige häufig genutzte Server:
- OpenAI Docs MCP: Durchsuche und lies die Entwicklungsdokumentation von OpenAI.
- Context7: Greife auf aktuelle Entwicklungsdokumentation zu.
- Figma Lokal und Remote: Greife auf deine Figma-Designs zu.
- Playwright: Steuere und untersuche einen Browser mit Playwright.
- Chrome Developer Tools: Steuere und untersuche Chrome.
- Sentry: Greife auf Sentry-Protokolle zu.
- GitHub: Nutze GitHub-Funktionen, die über
githinausgehen, etwa zum Verwalten von Pull Requests und Issues.