Model Context Protocol

Die ChatGPT-Desktop-App, Codex CLI und die IDE-Erweiterung unterstützen MCP server und verwenden für denselben Codex-Host eine gemeinsame MCP-Konfiguration.

Die unten aufgeführten unterstützten Serverfunktionen gelten für MCP server, die auf einem Codex-Host konfiguriert sind. Von Plugins bereitgestellte Tools können andere Funktionen besitzen.

Unterstützte MCP-Funktionen

• STDIO-Server: Server, die als lokaler Prozess ausgeführt werden (durch einen Befehl gestartet).
  • Umgebungsvariablen
• Streambare HTTP-Server: Server, auf die Sie über eine Adresse zugreifen.
  • Bearer-Token-Authentifizierung
  • OAuth-Authentifizierung einschließlich Client ID Metadata Documents (CIMD) und Dynamic Client Registration (DCR)
  • ChatGPT-Sitzungsauthentifizierung für vertrauenswürdige Erstanbieter-Server
• Serveranweisungen: Codex liest das bei der Initialisierung zurückgegebene MCP-Feld instructions und verwendet es zusammen mit den Tools des Servers als serverweite Anleitung.

Wenn Sie einen MCP server für Codex entwickeln oder verwalten, verwenden Sie instructions für toolübergreifende Workflows auf diesem Server, Einschränkungen und Ratenbegrenzungen. Formulieren Sie die ersten 512 Zeichen so, dass sie für sich allein verständlich sind. Dadurch stehen Codex die wichtigsten Hinweise zur Verfügung, wenn es über die Verwendung des Servers entscheidet.

Codex mit einem MCP server verbinden

Codex speichert die MCP-Konfiguration zusammen mit anderen Codex-Konfigurationseinstellungen in config.toml. Standardmäßig ist dies ~/.codex/config.toml, Sie können MCP server jedoch auch mit .codex/config.toml auf ein Projekt beschränken (nur bei vertrauenswürdigen Projekten).

Die ChatGPT-Desktop-App, Codex CLI und die IDE-Erweiterung verwenden diese Konfiguration gemeinsam. Nachdem Sie Ihre MCP server konfiguriert haben, können Sie zwischen diesen Clients wechseln, ohne die Einrichtung erneut durchzuführen.

In der ChatGPT-Desktop-App konfigurieren

1. Öffnen Sie Settings und wählen Sie anschließend MCP servers aus.
2. Wählen Sie Add server aus.
3. Geben Sie einen Namen ein, wählen Sie STDIO oder Streamable HTTP aus und geben Sie den Befehl oder die URL des Servers an.
4. Speichern Sie den Server und wählen Sie anschließend Restart aus.

Die Serverliste zeigt, welche Server aktiviert sind und für welche OAuth erforderlich ist. Wählen Sie Authenticate aus, wenn für einen OAuth-Server eine Anmeldung erforderlich ist. Geben Sie im Eingabefeld /mcp ein, um die verbundenen Server anzuzeigen.

MCP-gestützte Tools in ChatGPT im Web verwenden

Wenn Sie eine Unterhaltung mit lokalem Computerzugriff mit Work Cloud auf einem anderen Gerät fortsetzen, werden dadurch weder Plugins installiert noch Zugriffsrechte auf verbundene Konten erteilt.

Beim lokalen Computerzugriff mit Work Cloud gilt die TOML-Vorgabe für Unternehmen zu mcp_servers in Agent Security für lokale Ausführungsinstanzen. Für Cloud-Container gelten weiterhin die Richtlinien von Work Cloud. Lokale MCP server und Transportmechanismen sind in der Cloud möglicherweise nicht verfügbar; prüfen Sie Konnektivität und Authentifizierung separat.

Für Unternehmens-Hooks beim lokalen Computerzugriff mit Work Cloud gilt:

• Unternehmens-Hooks. Sofern für Ihren Workspace aktiviert, unterstützt der lokale Computerzugriff mit Work Cloud von Administratoren definierte MCP-Hooks, die bei unterstützten Lebenszyklus- und Tool-Ereignissen auf dem Cloud-Koordinator (Orchestrator) ausgeführt werden. Befehls-Hooks und Hooks aus der lokalen Konfiguration oder aus Plugins werden bei Cloud-Orchestrierung nicht unterstützt, auch wenn Tools lokal ausgeführt werden.
• Auditierung. Bevor Sie sich auf diese Hooks verlassen, testen Sie die Callback-Verbindung, prüfen Sie, welche Ereignisse sie empfängt, und untersuchen Sie, wie sich Fehler auf die Aufgabe auswirken. MCP-Hooks liefern kein vollständiges Auditprotokoll für die Compliance API.
• Einschränkungen: Befehls-Hooks und Hooks aus der lokalen Konfiguration oder aus Plugins werden bei Cloud-Orchestrierung nicht unterstützt, auch wenn Tools lokal ausgeführt werden. Für Privatnutzer unterstützt diese Funktion keine Hooks. Wenn sowohl die Orchestrierung als auch die Ausführung lokal erfolgen, funktionieren bestehende unterstützte Hooks weiterhin in rein lokalen Work- und Codex-Threads. Administratoren können für diese Workflows weiterhin unterstützte verwaltete Hooks in Agent Security konfigurieren.

Informationen zum Unterstützungsumfang finden Sie unter Hooks und in der Konfigurationsreferenz.

Installieren Sie in einem gehosteten ChatGPT Work-Chat ein Plugin, um dessen gebündelte Konnektoren und Remote-MCP-Tools zu verwenden. Nach der Installation können Chat und Work diese Tools verwenden. Workspace-Administratoren können steuern, welche Plugins und Tools verfügbar sind.

ChatGPT im Web liest keine lokalen Codex-Konfigurationsdateien und stellt das lokale Codex-Befehlsmenü nicht bereit. Öffnen Sie die Registerkarte Plugins, um verfügbare Tools zu durchsuchen und zu verwalten.

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 (einen kostenlosen MCP server für Entwicklerdokumentation) hinzuzufügen, können Sie den folgenden Befehl ausführen:

codex mcp add context7 -- npx -y @upstash/context7-mcp

Weitere CLI-Befehle

Führen Sie codex mcp list aus, um die konfigurierten Server anzuzeigen. Um alle verfügbaren MCP-Befehle anzuzeigen, führen Sie codex mcp --help aus. Führen Sie für einen Server, der OAuth unterstützt, codex mcp login <server-name> aus.

Terminal-Benutzeroberfläche (TUI)

Verwenden Sie in der codex TUI den Befehl /mcp, um Ihre aktiven MCP server anzuzeigen.

In der IDE-Erweiterung konfigurieren

1. Öffnen Sie das Zahnradmenü und wählen Sie dann MCP servers aus.
2. Wählen Sie Add server aus.
3. Geben Sie einen Namen ein, wählen Sie STDIO oder Streamable HTTP und geben Sie den Befehl oder die URL des Servers an.
4. Speichern Sie den Server und wählen Sie dann Restart extension aus.

Die Liste der MCP server zeigt, welche Server aktiviert sind und welche OAuth erfordern. Wählen Sie Authenticate aus, wenn für einen OAuth-Server eine Anmeldung erforderlich ist.

Mit config.toml konfigurieren

Für eine detailliertere Steuerung bearbeiten Sie ~/.codex/config.toml oder eine projektbezogene .codex/config.toml. In der Konfigurationsreferenz finden Sie eine durchsuchbare Liste aller unterstützten MCP-Optionen.

Konfigurieren Sie jeden MCP server mit einer [mcp_servers.<server-name>]-Tabelle in der Konfigurationsdatei.

STDIO-Server

• command (erforderlich): Der Befehl, der den Server startet.
• args (optional): Argumente, die an den Server übergeben werden.
• env (optional): Umgebungsvariablen, die für den Server festgelegt werden.
• env_vars (optional): Umgebungsvariablen, die zugelassen und weitergeleitet werden.
• cwd (optional): Arbeitsverzeichnis, aus dem der Server gestartet wird.
• experimental_environment (optional): Legen Sie remote fest, um den STDIO-Server über eine Remote-Ausführungsumgebung zu starten, sofern eine verfügbar ist.

env_vars kann einfache Variablennamen oder Objekte mit einer Quelle enthalten:

env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]

Zeichenfolgeneinträge und source = "local" werden aus der lokalen Umgebung von Codex gelesen. source = "remote" wird aus der Remote-Ausführungsumgebung gelesen und erfordert Remote-MCP-STDIO.

Streamable-HTTP-Server

• url (erforderlich): Die Serveradresse.
• auth (optional): Authentifizierung, die nach konfigurierten Bearer-Tokens und Autorisierungs-Headern versucht werden soll. Verwenden Sie oauth (die Standardeinstellung) für gespeicherte MCP-OAuth-Anmeldedaten. Verwenden Sie chatgpt, um die aktuelle ChatGPT-Sitzung für den vertrauenswürdigen Erstanbieter-Ursprung von ChatGPT zu verwenden, wobei gespeichertes OAuth als Fallback dient.
• bearer_token_env_var (optional): Name der Umgebungsvariable für ein Bearer-Token, das in Authorization gesendet werden soll.
• http_headers (optional): Zuordnung von Header-Namen zu statischen Werten.
• env_http_headers (optional): Zuordnung von Header-Namen zu Namen von Umgebungsvariablen (Werte werden aus der Umgebung abgerufen).
• http_headers_helper (optional): Lokaler Befehl, der ein JSON-Objekt mit Header-Namen und Zeichenfolgenwerten ausgibt, beispielsweise {"X-Auth": "temporary-token"}. Wird für HTTP-MCP-Verbindungen unterstützt, die aus der lokalen Umgebung hergestellt werden; nicht für STDIO-Server oder Verbindungen, die über eine Remote-Ausführungsumgebung hergestellt werden.

Codex speichert Hilfs-Header für die Verbindung im Cache. Nachdem ein POST mit demselben Ursprung 401 oder 403 zurückgibt, aktualisiert Codex die Header einmal und versucht es nur dann erneut, wenn die Hilfsfunktion geänderte Werte zurückgibt. Explizite Bearer-Tokens und OAuth-Anmeldedaten haben Vorrang vor einem von der Hilfsfunktion bereitgestellten Authorization-Header. Eine OAuth-Antwort mit 403, die einen unzureichenden Berechtigungsumfang meldet, löst keine Aktualisierung durch die Hilfsfunktion aus.

Wenn keine Anmeldedatenquelle aufgelöst werden kann, kann Codex ohne Authentifizierung eine Verbindung zum Server herstellen. Führen Sie codex mcp login <server-name> separat aus, um eine MCP-OAuth-Anmeldung zu starten.

Weitere Konfigurationsoptionen

• startup_timeout_sec (optional): Zeitlimit (Sekunden) für den Start des Servers. Standard: 10.
• tool_timeout_sec (optional): Zeitlimit (Sekunden) für die Ausführung eines Tools durch den Server. Standard: 60.
• enabled (optional): Legen Sie false fest, um einen Server zu deaktivieren, ohne ihn zu löschen.
• required (optional): Legen Sie true fest, damit der Start fehlschlägt, wenn dieser aktivierte Server nicht initialisiert werden kann.
• enabled_tools (optional): Positivliste für Tools.
• disabled_tools (optional): Sperrliste für Tools (wird nach enabled_tools angewendet).
• default_tools_approval_mode (optional): Standardmäßiges Genehmigungsverhalten für Tools von diesem Server. Unterstützte Werte sind auto, prompt, writes und approve. Im Modus writes wird bei Tools nachgefragt, die nicht als schreibgeschützt gekennzeichnet sind.
• tools.<tool>.approval_mode (optional): Überschreibung des Genehmigungsverhaltens für einzelne Tools.
• tools.<tool>.output_token_limit (optional): Positives Token-Budget für die Ausgabe eines Tools vor dem standardmäßigen Serialisierungsaufschlag von 20 %. Überschreibt das standardmäßige Budget des Modells für die Kürzung der Ausgabe dieses Tools.

Die Einstellung mcp_optional_startup_grace_ms auf oberster Ebene steuert, wie lange Codex beim Erstellen des anfänglichen Toolkatalogs auf optionale MCP server wartet. Der Standardwert beträgt 1000 Millisekunden. Legen Sie den Wert auf 0 fest, um stattdessen für jeden Server dessen startup_timeout_sec abzuwarten. Erforderliche Server verwenden weiterhin ihre Startzeitlimits.

OAuth-Clientregistrierung und Callbacks

Wenn Ihr Autorisierungsserver einen vorab registrierten OAuth-Client erfordert, geben Sie beim Hinzufügen des MCP server dessen Client-ID an:

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client

Übergeben Sie für einen vertraulichen Client zusätzlich --oauth-client-secret. Lesen Sie das Geheimnis aus einer Umgebungsvariablen ein:

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client --oauth-client-secret "$MCP_CLIENT_SECRET"

Diese Option erfordert eine nicht leere Client-ID und ein nicht leeres Geheimnis. Codex speichert das Geheimnis als mcp_servers.example.oauth.client_secret in config.toml. Halten Sie diese Datei vertraulich und nehmen Sie sie nicht in die Versionsverwaltung auf.

Codex zeigt die vollständige Callback-URL an, die Sie bei Ihrem Anbieter registrieren müssen:

OAuth callback URL: http://127.0.0.1/callback

Codex speichert den Callback zusammen mit der 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 einen stabilen Callback, wenn der Autorisierungsserver authorization_response_iss_parameter_supported: true angibt und einen Metadatenwert für issuer bereitstellt. Wenn die Unterstützung für den Aussteller nicht angegeben wird, hängt Codex eine serverspezifische Callback-ID an, beispielsweise http://127.0.0.1/callback/XuuuHAzzHOni. Vorhandene Clients ohne gespeicherten Callback verwenden weiterhin ihre Callback-ID-spezifische Weiterleitung.

Bei der Anmeldung hängt die Auswahl des Callbacks von der OAuth-Konfiguration und den Metadaten des Autorisierungsservers ab:

Der Fallback ändert die gespeicherte Callback-URL nicht. Codex leitet die Callback-ID aus der URL des MCP server einschließlich ihres Pfads und ihrer Abfragezeichenfolge ab. Dieselben Auswahlregeln gelten für die automatische und die explizite Anmeldung.

Legen Sie mcp_oauth_callback_url fest, wenn Sie einen benutzerdefinierten Callback-Pfad oder eine Remote-Ingress-URL für eine Devbox benötigen. Neu hinzugefügte, vorab registrierte Clients verwenden diese URL unverändert, wenn ihr Anbieter die Identifizierung des Ausstellers unterstützt. Andernfalls verwenden sie die konfigurierte URL mit angehängter serverspezifischer Callback-ID. Registrieren Sie immer den exakten Callback, den codex mcp add anzeigt.

Bei http://127.0.0.1-Callbacks ohne expliziten Port lässt Codex den Listener-Port in der angezeigten und gespeicherten URL weg und fügt den aktiven Listener-Port bei der Autorisierung ein. Diese Ersetzung gilt nicht für localhost, IPv6-Hosts, HTTPS-URLs oder Callbacks, die bereits einen Port enthalten. Autorisierungsserver müssen variable Loopback-Ports gemäß RFC 8252, Abschnitt 7.3 akzeptieren.

Legen Sie mit mcp_oauth_callback_port einen festen globalen Listener-Port fest oder verwenden Sie mcp_servers.<server-name>.oauth.callback_port, um ihn für einen einzelnen Server zu überschreiben. Ein expliziter Port in der Callback-URL konfiguriert den Listener nicht. Verwenden Sie für einen direkten Loopback-Callback http://127.0.0.1 ohne expliziten Port oder konfigurieren Sie denselben expliziten Port für die Callback-URL und den Listener. Ein über einen Proxy geleiteter Callback kann bewusst einen externen URL-Port verwenden, der vom lokalen Listener-Port abweicht. Lokale Callback-URLs werden an die lokale Schnittstelle gebunden; nicht lokale Callback-URLs werden an 0.0.0.0 gebunden.

Codex validiert jeden zurückgegebenen Wert für iss, bevor der Autorisierungscode ausgetauscht wird. Ein nicht übereinstimmender Wert für iss führt immer zur Ablehnung der Antwort. Wenn die Unterstützung für den Aussteller angegeben wird, führt auch ein fehlender Wert für iss zur Ablehnung. Bei keinem der beiden Fehler wird der Code ausgetauscht oder auf einen anderen Callback zurückgegriffen. Eine fehlerhafte Callback-URL oder eine angegebene Ausstellerunterstützung ohne Aussteller in den Metadaten bleibt ebenfalls ein nicht behebbarer Fehler. Siehe Benutzer authentifizieren.

Legen Sie mcp_servers.<server-name>.scopes in config.toml fest, um OAuth-Berechtigungsbereiche für einen Server auszuwählen. Um sie für eine einzelne Anmeldung zu überschreiben, führen Sie codex mcp login <name> --scopes read,write aus. Wenn keine der beiden Optionen festgelegt ist, verwendet Codex die bekannt gegebenen OAuth-Berechtigungsbereiche, sofern verfügbar.

Bei einer leeren Liste (scopes = []) wählt weiterhin die OAuth-Bibliothek die Berechtigungsbereiche aus. Die Bibliothek kann außerdem 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 aus, wenn der Autorisierungsserver client_id_metadata_document_supported: true bekannt gibt, none in token_endpoint_auth_methods_supported enthält und der Callback eine unterstützte Loopback-URL verwendet. Andernfalls verwendet Codex DCR, sofern verfügbar. Eine konfigurierte OAuth-Client-ID hat immer Vorrang und überspringt die Clientregistrierung.

Für CIMD ohne an den Aussteller gebundene Antworten verwendet Codex CLI ein von ChatGPT gehostetes Metadatendokument speziell für den jeweiligen MCP server:

https://chatgpt.com/oauth/codex/<callback_id>/client.json

Codex leitet <callback_id> aus der URL des MCP server ab und fügt die ID in den Loopback-Weiterleitungs-URI ein, zum Beispiel http://127.0.0.1:<port>/callback/<callback_id>. Das Metadatendokument registriert den entsprechenden Loopback-URI ohne Port. Autorisierungsserver müssen den bei der Anmeldung ausgewählten Port akzeptieren und dabei Host und Pfad genau abgleichen, wie von RFC 8252 vorgeschrieben. Benutzerdefinierte Callback-Hosts, -Pfade oder -Abfrageparameter erfordern DCR oder eine konfigurierte OAuth-Client-ID.

Codex CLI unterstützt außerdem ein stabiles, gemeinsam genutztes CIMD-Dokument:

https://chatgpt.com/oauth/codex/client.json

Codex CLI verwendet das stabile Dokument mit dem gemeinsamen Pfad /callback, wenn der Autorisierungsserver die Unterstützung für authorization_response_iss_parameter_supported: true bekannt gibt, einen gültigen Wert für issuer in seinen Metadaten bereitstellt und einen passenden iss in Autorisierungsantworten zurückgibt. Server ohne an den Aussteller gebundene Antworten verwenden das Callback-spezifische Dokument.

Um eine Registrierungsmethode für eine einzelne CLI-Anmeldung auszuwählen, verwenden Sie --oauth-client-registration:

codex mcp login <server-name> --oauth-client-registration cimd
codex mcp login <server-name> --oauth-client-registration dcr

Der Standardwert ist auto. Die gewählte Registrierung gilt nur für die aktuelle Anmeldung und wird nicht in config.toml gespeichert.

config.toml-Beispiele

[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 = 30000

Von Plugins bereitgestellte MCP server

Installierte Plugins können MCP server in ihrem Plugin-Manifest bündeln. Diese Server werden vom Plugin aus gestartet, sodass die Benutzerkonfiguration ihren Transportbefehl nicht festlegt. In der Benutzerkonfiguration lassen sich der Aktivierungsstatus und die Tool-Richtlinie unter plugins.<plugin>.mcp_servers.<server> weiterhin steuern.

[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"

Von Plugins bereitgestellte HTTP MCP server können OAuth-Einstellungen auch in .mcp.json deklarieren. Plugin-Manifeste verwenden die camelCase-Feldnamen clientId, callbackUrl und callbackPort:

{
  "mcpServers": {
    "sample": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "my-pre-registered-client",
        "callbackUrl": "http://127.0.0.1/callback/registered"
      }
    }
  }
}

Von Plugins bereitgestellte MCP server folgen denselben Regeln zur Callback-Auswahl wie andere MCP server. Wenn ein Plugin eine clientId bereitstellt, sein Anbieter keine an den Aussteller gebundenen Callbacks unterstützt und der callbackUrl die serverspezifische Callback-ID fehlt, ignoriert Codex diese URL für die Anmeldung und verwendet mcp_oauth_callback_url oder, falls nicht festgelegt, http://127.0.0.1/callback und hängt die Callback-ID an. Die konfigurierte callbackUrl bleibt unverändert.

Die Einstellung oauth.callbackPort eines Plugins überschreibt die globale Einstellung mcp_oauth_callback_port; wenn keine von beiden festgelegt ist, wählt Codex einen ephemeren Port. Der in callbackUrl eingebettete Port wählt nicht den Listener-Port aus. Konfigurieren Sie für einen direkten Loopback-Callback mit festem Port beide Werte identisch:

{
  "callbackUrl": "http://127.0.0.1:4321/callback/registered",
  "callbackPort": 4321
}

Bei Remote-Ingress oder einem anderen Proxy können sich der Port der Callback-URL und der lokale Listener-Port bewusst unterscheiden, wenn der Proxy an den konfigurierten Listener weiterleitet.

Beispiele für nützliche MCP server

Die Liste der MCP server wächst kontinuierlich. Hier sind einige häufig verwendete Server:

• OpenAI Docs MCP: OpenAI-Entwicklerdokumentation durchsuchen und lesen.
• Context7: Eine Verbindung zu aktueller Entwicklerdokumentation herstellen.
• Figma Local und Remote: Auf Ihre Figma-Designs zugreifen.
• Playwright: Einen Browser mit Playwright steuern und untersuchen.
• Chrome Developer Tools: Chrome steuern und untersuchen.
• Sentry: Auf Sentry-Protokolle zugreifen.
• GitHub: GitHub über die von git unterstützten Funktionen hinaus verwalten (beispielsweise Pull Requests und Issues).