MCP-Server in Codex CLI: hinzufügen, konfigurieren, authentifizieren
MCP-Server geben Codex neue Werkzeuge: aktuelle Dokumentation, Ihre Datenbank, Ihre GitHub-Repos. Dieses Walkthrough führt codex mcp add für einen lokalen stdio-Server aus, wechselt mit --url und OAuth zu einem Remote-Server, inspiziert die config.toml-Einträge hinter beiden und zeigt die Prüfungen, die beweisen, dass ein Server wirklich funktioniert.
Kurz zusammengefasst
- Codex liest MCP-Server aus ~/.codex/config.toml (global) oder .codex/config.toml (Projekt). Jeder Eintrag ist eine [mcp_servers.<name>]-Tabelle mit command/args für lokale stdio-Server oder url für Remote-Server.
- codex mcp add context7 -- npx -y @upstash/context7-mcp installiert einen stdio-Server, ohne die Datei anzufassen; codex mcp add <name> --url https://mcp.example.com/mcp registriert einen Remote-Server.
- Remote-Server authentifizieren sich beim ersten Verbindungsaufbau im Browser (Codex gibt Detected OAuth support aus und öffnet den Consent-Screen), oder später via codex mcp login <name>.
- Prüfen Sie mit /mcp in der TUI oder codex mcp list in der Shell. Codex 0.160.1 bewahrt außerdem SYSTEMROOT, TEMP und TMP beim Start von Remote-stdio-Servern mit Remote-Umgebungsvariablen.
OpenAI Codex + MCP: How to Install MCP Servers in Codex (Step by Step)
Kanal: Nathan Sebhastian8:48
OpenAI Codex Tutorial #9 - MCP Servers
Kanal: Net Ninja6:46
How to Add MCP Servers to OpenAI Codex CLI
Kanal: Snyk9:14
Connect Codex to an MCP server — official documentation
Offizielle Doku: developers.openai.com/codex
Jeder Befehl, jeder Dateipfad und jeder Config-Schlüssel auf dieser Seite wurde gegen die offizielle Codex-MCP-Dokumentation geprüft; die Videos oben sind die visuelle und faktische Quelle — inklusive der OAuth-Consent-Screens und des MCP-Menüs der Desktop-App.
Screenshots werden ihren Urhebern zugeordnet, mit Deep-Links zu den exakten Zeitstempeln. Keine Kamera-Bilder von Gesichtern.
MCP-Server zu Codex hinzufügen, Schritt für Schritt
Teil 1 — Ihr erster stdio-Server
- 1
Einen Server aus der offiziellen MCP-Doku wählen
Öffnen Sie developers.openai.com/codex/mcp — Codex' eigene Dokumentation hält die Befehlssyntax aktuell, und CLI und IDE-Erweiterung teilen sich diese Konfiguration. Die Doku listet fertige Server zum Ausprobieren: Context7 für tagesaktuelle Bibliotheksdokumentation, Figma, GitHub und mehr. Es gibt hunderte MCP-Server; für einen ersten Test nehmen Sie etwas Nur-Lese wie Context7.
Die offizielle Seite Connect Codex to an MCP server, mit der codex-mcp-add-Syntax und einem fertig kopierbaren Context7-Beispiel.Ansehen bei 0:20 - 2
Mit codex mcp add installieren
Kopieren Sie das Beispiel und führen Sie es in Ihrem Terminal aus: codex mcp add context7 -- npx -y @upstash/context7-mcp. Alles nach dem doppelten Strich ist der Befehl, der den Serverprozess startet. Codex antwortet "Added global MCP server 'context7'" — global heißt: Er ist in Ihre Konfiguration auf Benutzerebene gewandert und in jedem Projekt verfügbar.
Ein Befehl, kein Datei-Editing: Die CLI bestätigt, dass der Server in die globale Config kam.Ansehen bei 0:45 - 3
Ansehen, was die CLI in config.toml schrieb
codex mcp add ist nur ein Generator für ~/.codex/config.toml. Öffnen Sie die Datei und Sie finden [mcp_servers.context7] mit command = "npx" und args = ["-y", "@upstash/context7-mcp"]. Einträge lassen sich auch von Hand schreiben: Ergänzen Sie eine env-Tabelle für API-Keys, oder setzen Sie startup_timeout_sec (Standard 10) und tool_timeout_sec (Standard 60) für langsame Server. Hand-Editing ist genau der Weg, den die Snyk- und Net-Ninja-Videos in der Quellenkarte nehmen.
- 4
Codex starten und mit /mcp prüfen
Starten Sie codex in Ihrem Projekt und tippen Sie /mcp. Das MCP-Tools-Panel listet jeden konfigurierten Server mit Status, exaktem Startbefehl und den Tools, die er anbietet — Context7 zeigt query_docs und resolve-library-id. Fehlt hier etwas, landete der Eintrag in der falschen Datei oder der Server startete nicht.
Das /mcp-Panel in der Codex-TUI: context7 ist aktiviert und seine beiden Tools sind namentlich gelistet.Ansehen bei 1:05
Teil 2 — Benutzen, dann remote gehen
- 5
Einen Prompt bauen, der den Server wirklich nutzt
MCP-Tools werden bei Bedarf aufgerufen — fragen Sie also etwas, das sie braucht: "Prüfe mit Context7 die aktuelle Tailwind-CSS-Setup-Doku". Codex löst die Bibliothek auf, zieht die Doku durch den MCP-Server und zitiert die Quellen in der Antwort. Den Tool-Aufrufen zuzusehen ist Ihr Beweis, dass der Server Ende-zu-Ende funktioniert.
Codex' Antwort zitiert die exakten Context7-Doku-URLs, die es durch den MCP-Server gezogen hat.Ansehen bei 1:30 - 6
Einen Remote-Server mit --url hinzufügen
Viele Anbieter hosten ihren MCP-Server auch remote — ohne lokalen Prozess, ohne npx. Registrieren Sie einen mit codex mcp add context7 --url https://mcp.context7.com/mcp. Codex erkennt OAuth-Unterstützung automatisch, gibt "Detected OAuth support. Starting OAuth flow..." aus und öffnet Ihren Browser zur Autorisierung. In config.toml ist der Eintrag nur url = "https://mcp.context7.com/mcp" unter [mcp_servers.context7].
Der komplette Remote-Flow in einem Terminal: das --url-Add, die OAuth-Erkennung, die Autorisierungs-URL und Successfully logged in.Ansehen bei 2:22 - 7
Den OAuth-Consent-Screen freigeben
Der Browser fragt, ob Codex im Namen des Anbieters auf Ihr Konto zugreifen darf. Prüfen Sie die angefragten Scopes, klicken Sie Allow, und das Terminal bestätigt "Successfully logged in". Für Server ohne OAuth-Flow authentifizieren Sie sich separat mit codex mcp login <name>; Token-basierte Server nehmen stattdessen bearer_token_env_var, das auf eine Umgebungsvariable zeigt.
Context7s Consent-Screen: Prüfen Sie die Scopes, die Codex anfragt, dann Allow.Ansehen bei 2:02 - 8
Einen Server auf ein Projekt eingrenzen mit .codex/config.toml
Server, die nur in einem Repo Sinn ergeben — wie DBHub, ein stdio-Server, der mit Ihrer Datenbank spricht — gehören in die Projekt-Konfiguration. Legen Sie im Repo einen .codex-Ordner an, fügen Sie eine config.toml mit dem Eintrag [mcp_servers.dbhub] hinzu und übergeben Sie Ihren Connection-String über das Argument --dsn (passen Sie ihn vom Postgres-Beispiel der Doku an MySQL oder Ihren Stack an). Committen Sie, und Ihre Teamkollegen bekommen denselben Server; der Ordner muss ein vertrauenswürdiges Projekt sein, damit er lädt.
Eine Projekt-.codex/config.toml: DBHub läuft über stdio mit dem Datenbank-DSN des Repos in den args.Ansehen bei 3:30
Teil 3 — Echte Server und Kontrolle ab Tag zwei
- 9
Ihre Datenbank über MCP-Tools abfragen
Mit konfiguriertem DBHub fragen Sie Codex zur Datenbank: "Finde die Petco-Datenbank und erkläre die Tabellen", dann "Was ist das meistverkaufte Produkt?". Codex ruft die Tools describe_table und execute_sql des Servers auf, fragt vor der SQL-Ausführung um Erlaubnis und antwortet mit echten Zahlen aus Ihren Daten. Das ist der schnellste Weg, Schemata zu debuggen und Daten zu validieren, während man am Backend arbeitet.
Codex führte dbhubs execute_sql-Tool aus und antwortete mit dem meistverkauften Produkt und seinem Umsatz.Ansehen bei 4:40 - 10
GitHub über seinen Remote-MCP-Server anbinden
Das README von github/github-mcp-server dokumentiert das Codex-Setup: Fügen Sie einen [mcp_servers.github]-Eintrag mit url = "https://api.githubcopilot.com/mcp/" hinzu und authentifizieren Sie sich entweder über OAuth oder indem Sie einen Personal Access Token als Umgebungsvariable exportieren (legen Sie einen fine-grained PAT unter GitHub Settings, Developer settings an, mit Administration und Contents). Remote-first-Server wie dieser und der Figma-MCP-Server folgen demselben Muster wie in Schritt 6.
GitHubs MCP-Server-Installationsanleitung: der Codex-CLI-Eintrag plus der OAuth/PAT-Authentifizierungshinweis.Ansehen bei 5:22 - 11
Neu starten und die Tools arbeiten lassen
Starten Sie codex neu und schauen Sie auf den Banner: "Starting servers (0/3): context7, dbhub, github". Jetzt genügt eine einzelne Anweisung wie "Fork das Repo openai/codex in mein Konto" — Codex wählt GitHubs Fork-Tool, fragt um Freigabe und erledigt es. Kein Setup pro Aufgabe: Die Tools sind ab jetzt einfach Teil jeder Sitzung.
- 12
Server verwalten mit codex mcp list und der Desktop-App
codex mcp list gibt jeden konfigurierten Server aus der Shell aus; einen zu entfernen heißt, seinen Block aus config.toml zu löschen und den Befehl zur Kontrolle erneut auszuführen. Desktop-App und IDE-Erweiterung lesen dieselbe ~/.codex/config.toml, daher tauchen hier installierte Server in der Desktop-App unter Settings, MCP servers mit An/Aus-Schaltern auf.
Die MCP-Server-Einstellungen der Codex-Desktop-App: context7, dbhub und github mit Schaltern, dazu empfohlene Server.Ansehen bei 7:30
Lokale stdio- vs. Remote-MCP-Server in Codex
Beide Arten leben in denselben [mcp_servers.*]-Tabellen und erscheinen im selben /mcp-Panel — der Unterschied ist, wo der Server läuft und wie er sich authentifiziert. Wählen Sie pro Server, nicht pro Projekt.
- 1Lokal stdio: Codex startet selbst einen Prozess mit command und args — typischerweise npx oder eine Binärdatei. Er läuft auf Ihrer Maschine und erreicht daher localhost-Dienste wie eine Dev-Datenbank (so befragte DBHub im Walkthrough MySQL), aber Sie stellen Runtime und Updates.
- 2Remote: Codex spricht mit einer gehosteten url über streamables HTTP. Kein Prozess, den man am Leben hält, und die Auth ist zentralisiert — OAuth als Standard, oder bearer_token_env_var und http_headers für Token-Setups. Das Doku-Beispiel selbst ist [mcp_servers.figma] mit url = "https://mcp.figma.com/mcp".
- 3Remote-ausgeführtes stdio: ein experimenteller Mittelweg. experimental_environment = "remote" auf einem stdio-Eintrag verlagert seine Ausführung zu einem Remote-Executor, wobei env_vars entscheidet, welche Variablen reisen — einschließlich Einträgen mit source = "remote". Das ist der Weg, den Codex 0.160.1 gehärtet hat.
- 4Geltungsbereich: codex mcp add schreibt immer in die globale ~/.codex/config.toml; projektspezifische Server kommen in die .codex/config.toml im Repo (nur vertrauenswürdige Projekte). Global für Tools, die Sie überall wollen, Projekt für alles mit umgebungsspezifischen Zugangsdaten.
- 5Regler für beide: startup_timeout_sec (Standard 10) und tool_timeout_sec (Standard 60) für langsame Server, enabled/disabled_tools, um per Allow-Liste festzulegen, was Codex aufrufen darf, und required = true, wenn ein Server hochkommen muss oder Codex den Start verweigern soll.
Ein praktischer Standard: Nur-Lese-Doku-Server wie Context7 dürfen global sein; alles, was Zugangsdaten oder Daten anfasst — DBHub, GitHub mit PAT — gehört in die Projekt-Konfiguration, wo man es prüfen und mit dem Repo widerrufen kann.
Konfiguriert, aber kaputt: die üblichen Verdächtigen
Die meisten MCP-Fehler in Codex sind Scope-, Timeout- oder Authentifizierungsprobleme — in dieser Reihenfolge. Gehen Sie diese Liste durch, bevor Sie am Server selbst schrauben.
- 1Server fehlt in /mcp: Prüfen Sie, welche Datei Sie editiert haben. Globale Einträge liegen in ~/.codex/config.toml; Projekt-Einträge in .codex/config.toml, und nur für vertrauenswürdige Projekte. codex mcp list aus der Shell zeigt, was Codex wirklich sieht.
- 2Server läuft beim Start ins Timeout: startup_timeout_sec ist standardmäßig 10 Sekunden, und ein kalter npx-Download eines großen Pakets übersteigt das leicht. Installieren Sie das Paket vor oder erhöhen Sie startup_timeout_sec des Eintrags.
- 3Tool-Aufrufe schlagen mit 401/403 fehl: Die Zugangsdaten fehlen oder sind abgelaufen. Führen Sie codex mcp login <name> für OAuth-Server aus, oder setzen Sie bearer_token_env_var und exportieren Sie die Variable. Danach sollte /mcp den Server wieder als aktiviert zeigen.
- 4Remote-stdio-Server stürzt mit seltsamen Windows-Fehlern ab: Vor 0.160.1 konnte der Start eines Remote-stdio-MCP-Servers mit explizit konfigurierten Remote-Umgebungsvariablen SYSTEMROOT, TEMP und TMP verlieren und so die Startumgebung des Windows-Executors brechen. Aktualisieren Sie auf 0.160.1 oder neuer.
- 5Server startet, aber Antworten sind falsch oder leer: Viele gehostete Server brauchen einen eigenen API-Key, selbst über OAuth — Context7 will etwa einen API-Key per env. Schauen Sie in der Anbieter-Doku nach dem exakten env-Namen und ergänzen Sie ihn in der env-Tabelle des Eintrags.
Zwei nützliche Hebel beim Debuggen: Setzen Sie required = true auf einen Server, von dem Sie abhängen, damit Codex nie stillschweigend ohne ihn startet, und enabled = false, um einen auszuschalten, ohne seine Config zu löschen.