# Codex MCP einrichten: React-UI mit echten Komponenten > Codex MCP für React-UI einrichten, getestet mit Codex CLI 0.162.1: config.toml-Eintrag, Key-Variable, AGENTS.md-Regeln, Prompts für echte Blocks, Fehlerhilfe. - Autor: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI - Veröffentlicht: 13. Okt. 2026 - Kategorie: [UI mit KI-Agenten bauen](https://wingo-ui.com/de/blog/category/ai-agents) - Lesezeit: 11 Min. - Kanonische URL: https://wingo-ui.com/de/blog/codex-mcp-setup-react-ui - Englische Fassung: https://wingo-ui.com/blog/codex-mcp-setup-react-ui ## Kurz gesagt Führ npx wingo-ui@latest login aus, danach npx wingo-ui@latest agents install codex. Der Befehl legt eine Tabelle [mcp_servers.wingo-ui] in ~/.codex/config.toml an und einen kurzen Regelblock in ~/.codex/AGENTS.md; ist WINGO_UI_API_KEY exportiert, nutzt die Tabelle url und bearer_token_env_var, sonst startet sie den lokalen Proxy npx -y wingo-ui@latest mcp. Starte Codex neu, prüf den Server mit codex mcp list oder /mcp und nenn in deinen Prompts den Block beim Namen, damit Codex search_components und get_block aufruft, bevor es Code schreibt. OpenAI Codex schreibt React schnell. Ohne Vorgaben schreibt es aber die Komponenten, die es aus dem Training kennt: eine Settings-Seite von Grund auf, ein Modal ohne Mobile-Layout, einen Button mit selbstgebautem Spinner. Codex MCP ändert das: Über eine MCP-Verbindung zu deiner Komponentenbibliothek kann Codex den echten Katalog durchsuchen, Props mit ihren Defaults lesen und den Quellcode per CLI installieren, bevor es eine Zeile schreibt. Dieses Tutorial richtet das komplett mit unserer Bibliothek Wingo UI ein: den Key, den Eintrag in `config.toml`, die Regeldatei, den Neustart und den Check, drei Prompts, die ganze Screens aus echten Blocks bauen, und die Fehler, auf die du wahrscheinlich stößt. Getestet haben wir am 13. Oktober 2026 mit Codex CLI 0.162.1, unserer CLI 1.0.3 und Wingo UI Release 1.8.0. Die Config-Syntax haben wir am selben Tag mit der [MCP-Doku zu Codex](https://developers.openai.com/codex/mcp) und der [Config-Referenz](https://developers.openai.com/codex/config-reference) von OpenAI abgeglichen. Was ein MCP-Server für Komponenten ist und warum Agenten einen brauchen, steht in unserem [Guide zu MCP für Komponentenbibliotheken](https://wingo-ui.com/de/blog/component-library-mcp-guide). Dieser Beitrag ist die Codex-Hälfte davon, im Detail. ## Was brauchst du für einen Codex MCP Server? Wer einen Codex MCP Server einrichten will, braucht vier Teile. Die beiden Dateien schreibt ein einziger Befehl: | Teil | Wo | Wer es schreibt | | --- | --- | --- | | Ein API-Key | `~/.config/wingo-ui` oder `WINGO_UI_API_KEY` | `npx wingo-ui@latest login` oder deine Kontoseite | | Der Eintrag für den MCP-Server | `~/.codex/config.toml`, Tabelle `[mcp_servers.wingo-ui]` | `npx wingo-ui@latest agents install codex` | | Die Regeln | `~/.codex/AGENTS.md`, ein markierter Block | derselbe Befehl | | Ein Neustart | Codex liest beide Dateien beim Start | du | ## Schritt 1: Wie bekomme ich einen Key? Melde die CLI einmal pro Rechner an: ```bash npx wingo-ui@latest login ``` Der Befehl öffnet den Browser, in dem du das Gerät bestätigst, und speichert dann einen API-Key in `~/.config/wingo-ui`. Ein Free-Konto braucht nur eine E-Mail-Adresse. Der Key entscheidet, was Codex bekommt: - **Kein Key:** Suche, Props, Doku, Designregeln und Tokens funktionieren, nur ohne Quellcode. Wir haben `get_account_status` ohne Key aufgerufen, und der Server hat genau das gemeldet. - **Free-Key:** Dazu kommt der Quellcode der 75 kostenlosen Items, darunter der [Button](https://wingo-ui.com/components/button). - **Pro-Key:** Dazu kommt der Quellcode aller Items, auch von Blocks wie [Settings Page](https://wingo-ui.com/components/settings-page) und [Login Page](https://wingo-ui.com/components/login-page), die wir unten nutzen. Für das HTTP-Setup in Schritt 3 brauchst du den Key außerdem als Wert. Leg auf der Seite für API-Keys in deinem Konto einen eigenen Key für Codex an, dann kannst du ihn später einzeln widerrufen. ## Schritt 2: Was schreibt agents install codex? Führ den Befehl im Projekt aus: ```bash npx wingo-ui@latest agents install codex ``` Ohne `WINGO_UI_API_KEY` in der Umgebung hat er auf einem frischen Rechner diese Zeilen ausgegeben (plus einen Hinweis zum Key): ```text Coding agents (Codex; MCP over the local stdio proxy) created ~/.codex/AGENTS.md created ~/.codex/config.toml ``` Dass standardmäßig deine User-Config beschrieben wird, ist Absicht. Laut der Config-Referenz von OpenAI lädt Codex projektbezogene Config-Dateien nur dann, wenn du dem Projekt vertraust ([Quelle](https://developers.openai.com/codex/config-reference)), und bei nicht vertrauten Projekten ignoriert Codex den ganzen Ordner `.codex/`. Ein Server in deinem Home-Ordner funktioniert in jedem Projekt, ob vertraut oder nicht. Für ein Repository, das dein Team teilt, schreibt `--scope project` stattdessen `.codex/config.toml` und einen markierten Block in die `AGENTS.md` des Projekts. In unserem Testprojekt hatte create-next-app schon eine `AGENTS.md` angelegt; die CLI hat ihren Block angehängt und den Rest stehen lassen. Ein zweiter Lauf ändert nichts, und andere Server in der Datei bleiben erhalten. ### Soll Codex HTTP oder den stdio-Proxy nutzen? Die CLI wählt HTTP, wenn `WINGO_UI_API_KEY` gesetzt ist, sonst den Proxy; mit `--mcp http` oder `--mcp stdio` entscheidest du selbst. So sieht die Tabelle `mcp_servers` in der Codex config.toml für jede Variante aus: ```toml # HTTP: Codex ruft den Server direkt auf und schickt $WINGO_UI_API_KEY als Bearer-Token [mcp_servers.wingo-ui] url = "https://wingo-ui.com/mcp" bearer_token_env_var = "WINGO_UI_API_KEY" ``` ```toml # stdio: Codex startet einen lokalen Proxy, der den von wingo-ui login gespeicherten Key nutzt [mcp_servers.wingo-ui] command = "npx" args = ["-y", "wingo-ui@latest", "mcp"] ``` `bearer_token_env_var` enthält den Namen einer Variable, nie den Key selbst. Die Datei kannst du also gefahrlos synchronisieren oder teilen. HTTP spart einen Prozess und startet sofort. Der Proxy braucht keine Umgebungsvariable: Hast du `login` schon ausgeführt, läuft er. Nimm den Proxy, wenn du Codex aus einem Editor oder einer App startest, die dein Shell-Profil vielleicht nicht lädt. ## Schritt 3: Wie exportiere ich den Key für Codex? Nur im HTTP-Modus. Codex liest die Variable beim Start, sie muss also in der Umgebung der Shell stehen, die Codex startet. Trag sie in dein Shell-Profil ein: ```bash # ~/.zshrc oder ~/.bashrc export WINGO_UI_API_KEY="wui_..." ``` Öffne ein neues Terminal und prüf, ob die Variable da ist, bevor du Codex startest: `echo $WINGO_UI_API_KEY | cut -c1-4` sollte `wui_` ausgeben. ## Schritt 4: Wie prüfe ich die Verbindung? Starte Codex neu und prüf dann in der Shell. In unserem Testprojekt hat `codex mcp list` Folgendes ausgegeben: ```text Name Url Bearer Token Env Var Status Auth wingo-ui https://wingo-ui.com/mcp WINGO_UI_API_KEY enabled Bearer token ``` `codex mcp get wingo-ui` zeigt den Transport (`streamable_http` bei HTTP). In einer Codex-Session tippst du `/mcp`, um die aktiven Server zu sehen. Stell dann eine Frage, die nur der Server beantworten kann: ```text Ruf get_account_status auf dem MCP-Server wingo-ui auf und sag mir, was er antwortet. ``` Nennt die Antwort deinen Plan, ist der Key beim Server angekommen. Steht dort „Anonymous“, hat sich Codex ohne Key verbunden. Dann prüf Schritt 3. ## Was geben die AGENTS.md-Regeln Codex vor? Wann Codex welches Tool aufruft, wie es installiert und was es nie tun soll. Das ist der Block, den die CLI geschrieben hat, zwischen Versionsmarkern, die `npx wingo-ui@latest agents update` später neu schreibt: ```md ## Wingo UI This project builds its UI with Wingo UI (React 19 + Tailwind CSS v4 components installed as source, see `wingo-ui.json`). - Before writing UI, use the `wingo-ui` MCP tools: `search_components` to find what exists (blocks for whole screens), `get_component` / `get_block` for props and usage, `get_design_rules` for tokens, sizes, motion and mobile rules. Never recreate a component the library has. - Install with `npx wingo-ui@latest add `. At the start of UI work run `check_updates` (or `npx wingo-ui@latest outdated`) and mention updates; update with `npx wingo-ui@latest update`. - Semantic tokens only (`bg-background`, `bg-surface`, `text-muted-foreground`, `border-border`), configure components through props, keep `cn()`, `data-slot` and license headers in copied files. Check 390px and 1440px, light and dark. - No MCP tools available? The CLI has `search`, `info`, `add`, `outdated`, `update`; the docs for models are at https://wingo-ui.com/llms.txt. ``` Wie Codex ihn findet, beschreibt der [AGENTS.md-Guide](https://developers.openai.com/codex/guides/agents-md) von OpenAI: zuerst `~/.codex/AGENTS.md` (oder `AGENTS.override.md`), dann eine Datei pro Ordner vom Projektstamm bis zu dem Ordner, in dem du Codex gestartet hast. Die Dateien werden in dieser Reihenfolge zusammengefügt, bis `project_doc_max_bytes` erreicht ist, standardmäßig 32 KiB. Dateien näher an deinem Arbeitsordner kommen später, die eigenen Regeln eines Projekts können den globalen Block also verfeinern. Genau diese Reihenfolge ist der eine Haken am Standard-Setup: Der globale Block sagt in jedem Repository auf deinem Rechner, dass das Projekt seine UI mit Wingo UI baut. Arbeitest du auch an Projekten mit einer anderen Bibliothek, installier dort mit `--scope project` oder ergänze in deren `AGENTS.md` eine Zeile, welche Bibliothek sie nutzen. Wenn du eine ausführlichere Codex AGENTS.md für React als Vorlage willst, mit Befehlen, Tokens und den Checks für jeden Screen, findest du eine in unserem [Vergleich AGENTS.md vs. CLAUDE.md](https://wingo-ui.com/de/blog/agents-md-vs-claude-md-react). ## Mit welchen Prompts baut OpenAI Codex React-UI aus echten Komponenten? Mit Prompts, die den Block beim Namen nennen, sagen, woher seine Daten kommen, und eine Liste dessen verlangen, was noch simuliert ist. Das gilt für jede React-UI-Aufgabe in OpenAI Codex, egal mit welcher Bibliothek. Unsere Blocks bringen funktionierende Beispiel-Handler mit, damit ihre Demos laufen, und jeder Handler, den du nicht übergibst, behält sein Beispielverhalten. Hier sind drei Prompts, mit den Tools, zu denen die Regeln und die Server-Anweisungen Codex führen. Jedes dieser Tools haben wir direkt am Server aufgerufen, um seine Antwort zu prüfen; wie zuverlässig ein bestimmtes Modell ihnen folgt, schwankt. | Prompt | Tools, die Codex aufrufen sollte | Danach | | --- | --- | --- | | Settings-Screen | `search_components` (kind block), `get_block` für `settings-page`, `get_design_rules` für Formulare | `npx wingo-ui@latest add settings-page` | | Login | `search_components`, `get_block` für `login-page` | `npx wingo-ui@latest add login-page` | | Komponente tauschen | `check_updates`, `search_components`, `get_component` für `button` | `npx wingo-ui@latest add button` | ### Prompt 1: ein Settings-Screen aus settings-page ```text Bau app/settings mit dem Wingo-UI-Block settings-page. Lies zuerst seine Props mit get_block. Behalte nur die Abschnitte Profile, Account und Notifications. Lade Profil und Konto auf dem Server aus getSessionUser() in lib/session.ts und speichere jeden Abschnitt mit PATCH /api/settings/
. Unser Produkt heißt Harbor: Ersetze den Beispiel-Produktnamen in jedem angezeigten Label. Liste jeden on*-Handler und jede verify*-Funktion auf, die noch auf dem Beispiel-Default steht. ``` Die Abschnitts-IDs des Blocks sind seine eigenen (`profil`, `cont`, `notificari`, `facturare`, `securitate`, `pericol`); die Labels auf dem Screen sind englisch. Ein guter Lauf endet mit einer Client-Komponente wie dieser, die wir gegen Release 1.8.0 typgeprüft haben: ```tsx // app/settings/settings-screen.tsx "use client"; import Link from "next/link"; import { SettingsPage, type SettingsAccount, type SettingsFormSection, type SettingsProfile, type SettingsSaveValues, } from "@/components/blocks/settings-page"; async function patch(path: string, body: unknown) { const res = await fetch(path, { method: "PATCH", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body), }); // bei einem Fehler bleibt der Entwurf erhalten und die Save-Bar zeigt diese Meldung if (!res.ok) throw new Error("Deine Änderungen wurden nicht gespeichert. Versuch es noch einmal."); } type SettingsScreenProps = { profile: SettingsProfile; account: SettingsAccount }; export function SettingsScreen({ profile, account }: SettingsScreenProps) { return ( patch(`/api/settings/${section}`, values) } onPreferenceChange={(preference, value) => patch("/api/settings/preferences", { preference, value })} labels={{ photoDescription: "Erscheint überall in Harbor neben deinem Namen.", workspaceAddressDescription: "Unter dieser Adresse öffnet dein Team Harbor.", workspaceDomain: "harbor.app/", }} linkComponent={(props) => } /> ); } ``` Die Liste, die Codex zurückgeben sollte, enthält `onUpload` (den Foto-Upload), `onEmailChange` und `verifyEmailCode` (den Dialog zum Ändern der E-Mail, in dem der Code 123456 akzeptiert wird, bis du die Funktion anbindest) sowie `checkWorkspaceAddress`. In der Demo unten schlägt ein Speichern absichtlich fehl. So siehst du, was deine Nutzer sehen, wenn deine API einen Speichervorgang ablehnt. > Live-Demo (Settings Page): Öffne Profile, ändere das Feld Full name und drück Save: Diese Demo verwirft das erste Speichern, die Leiste zeigt den Fehler und behält deine Änderung, und das nächste Save geht durch. Probier sie unter [Settings Page](https://wingo-ui.com/components/settings-page) aus und installier sie mit `npx wingo-ui@latest add settings-page`. ### Prompt 2: ein Login aus login-page ```text Bau /login aus dem Wingo-UI-Block login-page, zentriertes Layout, keine Social-Provider. Anmeldung mit Passwort oder einem 6-stelligen E-Mail-Code über unsere /api/auth-Routen, bei Erfolg weiter zu /dashboard, und ersetze jeden Northwind-String in den Labels durch Harbor. Liste jeden Handler auf, der noch auf seinem simulierten Default steht. ``` Die Beispielmarke ist hier wichtig: Die Default-Labels des Blocks nennen Northwind CRM im App-Namen und in der Sign-in-Beschreibung und Northwind Software in der Copyright-Zeile, und das Default-Logo ist das Northwind-Logo. Das erwartete Ergebnis: ```tsx // app/login/login-screen.tsx "use client"; import Link from "next/link"; import { useRouter } from "next/navigation"; import { LoginPage, type SignInValues, type VerifyCodeContext } from "@/components/blocks/login-page"; async function post(path: string, body: unknown) { const res = await fetch(path, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body), }); if (!res.ok) { const data = (await res.json().catch(() => null)) as { message?: string } | null; // die Seite zeigt die Meldung eines abgelehnten Promise in ihrem Fehler-Alert throw new Error(data?.message ?? "Etwas ist schiefgelaufen. Versuch es noch einmal."); } } export function LoginScreen() { const router = useRouter(); return ( Harbor} labels={{ appName: "Harbor", signInDescription: "Melde dich bei deinem Harbor-Konto an, um weiterzumachen.", copyright: "© 2026 Harbor Inc.", }} onSignIn={(values: SignInValues) => post("/api/auth/sign-in", values)} onSendCode={(email) => post("/api/auth/send-code", { email })} onVerifyCode={(code: string, context: VerifyCodeContext) => post("/api/auth/verify-code", { code, ...context })} onForgot={(email) => post("/api/auth/forgot", { email })} onReset={(password) => post("/api/auth/reset", { password })} onSuccess={() => router.push("/dashboard")} registerHref="/signup" linkComponent={(props) => } /> ); } ``` Ohne `onVerifyCode` akzeptiert die Code-Ansicht 123456 für jeden. Das ist die Zeile im Bericht des Agenten, die du am dringendsten sehen willst. Mit den Methoden oben und ausgeblendeten Providern sollte die Liste leer zurückkommen. > Live-Demo (Login Page): Melde dich mit einer beliebigen E-Mail und einem Passwort unter 8 Zeichen an, um den Fehler-Alert zu sehen, und öffne dann Forgot password: Die eingegebene E-Mail wird übernommen. Probier sie unter [Login Page](https://wingo-ui.com/components/login-page) aus und installier sie mit `npx wingo-ui@latest add login-page`. ### Prompt 3: eine selbstgeschriebene Komponente tauschen ```text Führ zuerst check_updates für die Items in wingo-ui.json aus. Such dann jeden Button in app/account, der beim Speichern einen eigenen Spinner rendert, und ersetze ihn durch den Wingo-UI-Button. Hol seine Props mit get_component, installier ihn mit der CLI und zeig mir den Diff. ``` Der Kern ist `get_component`: Unser Button hat einen `loading`-Prop, damit fallen der selbstgebaute Spinner und das Jonglieren mit `disabled` weg: ```tsx import { Button } from "@/components/ui/button"; export function SaveButton({ saving, onSave }: { saving: boolean; onSave: () => void }) { return ( ); } ``` Solange `saving` true ist, wird das Label durch einen Spinner und „Wird gespeichert“ ersetzt, die Breite bleibt gleich, Klicks werden ignoriert und `aria-busy` ist gesetzt. ## Was geht schief, und wie behebe ich es? - **Der Server fehlt in einem Projekt, dem Codex nicht vertraut.** Du hast mit `--scope project` installiert, und Codex vertraut dem Ordner nicht. In unserem Test hat `codex mcp list` „No MCP servers configured yet“ ausgegeben, bis wir den Ordner als vertrauenswürdig markiert hatten. Das Vertrauen steht in `~/.codex/config.toml` als `projects..trust_level`; wir haben `trust_level = "trusted"` unter einer Tabelle `[projects.""]` ergänzt, und der Server war da. Vertrau dem Projekt, wenn Codex fragt, oder installier mit dem Standard-Scope in deine User-Config. - **Die Key-Variable fehlt.** Codex hat für den HTTP-Eintrag kein Token zum Senden. Prüf das mit der `echo`-Zeile aus Schritt 3 in der Shell, aus der du Codex startest, exportier `WINGO_UI_API_KEY` in deinem Profil, öffne ein neues Terminal und starte Codex neu. Ein Editor oder eine Desktop-App lädt dein Shell-Profil möglicherweise nicht; wechsle dann mit `npx wingo-ui@latest agents install codex --mcp stdio` zum Proxy. - **Der stdio-Proxy läuft beim ersten Start in ein Timeout.** `npx` lädt das Paket beim ersten Mal herunter, und Codex wartet standardmäßig 10 Sekunden (`startup_timeout_sec`). Ergänze `startup_timeout_sec = 30` in der Tabelle `[mcp_servers.wingo-ui]` oder führ vorher einmal `npx -y wingo-ui@latest --version` aus. - **Ein Free-Key und ein Pro-Block.** `get_block` liefert für `settings-page` weiterhin Props und Usage, aber keinen Quellcode, und `npx wingo-ui@latest add settings-page` bricht mit „Settings Page is part of Wingo UI Pro“ ab. Lass Codex stattdessen aus kostenlosen Komponenten bauen oder steig auf Pro um. - **Codex schreibt UI, ohne die Tools aufzurufen.** Prüf, ob der Regelblock in einer `AGENTS.md` steht, die Codex liest (`npx wingo-ui@latest agents status` sagt es dir), und nenn den Block im Prompt beim Namen. ## Wo fange ich an? Führ `npx wingo-ui@latest login` aus, dann `npx wingo-ui@latest agents install codex`, starte Codex neu und probier Prompt 3 zuerst mit einer kostenlosen Komponente. Die [Doku zum MCP-Server](https://wingo-ui.com/docs/mcp) listet jedes Tool, und die [Doku zu Coding Agents](https://wingo-ui.com/docs/agents) behandelt die anderen Agenten und die Optionen `--scope` und `--mcp`. Die Blocks Settings Page und Login Page gehören zu Wingo UI Pro, mehr dazu auf der [Preisseite](https://wingo-ui.com/de/pricing). Alles, was wir für Coding Agents liefern, steht auf einer Seite, [Wingo UI für KI-Agenten](https://wingo-ui.com/de/ai). Weitere Setups wie dieses findest du unter [UI mit KI-Agenten bauen](https://wingo-ui.com/de/blog/category/ai-agents), darunter das [Claude Code shadcn MCP Setup](https://wingo-ui.com/de/blog/claude-code-shadcn-mcp-setup) (auf Englisch) für dieselbe Aufgabe in Claude Code. ## Komponenten in diesem Artikel - [Button](https://wingo-ui.com/components/button) (Free): The React button component every screen starts with: five variants, six tones, all sizes, and a loading state that never jumps. Installation: `npx wingo-ui@latest add button` - [Login Page](https://wingo-ui.com/components/login-page) (Pro): A React login page with password, magic link or code sign-in, Google, Apple and Microsoft buttons, two-step codes and password recovery. Installation: `npx wingo-ui@latest add login-page` - [Settings Page](https://wingo-ui.com/components/settings-page) (Pro): A React account settings page for a back office: profile, account, notifications, billing, security and a danger zone, with a save bar. Installation: `npx wingo-ui@latest add settings-page` ## Häufige Fragen ### Wo speichert Codex MCP-Server? In config.toml: ~/.codex/config.toml für alle Projekte oder .codex/config.toml in einem Projekt. Laut OpenAI-Doku lädt Codex die Projektdatei nur, wenn du dem Projekt vertraust. Deshalb schreibt unsere CLI standardmäßig in die Datei im Home-Ordner. ### Wie übergebe ich in Codex einen API-Key an einen Remote-MCP-Server? Setz bearer_token_env_var auf den Namen einer Umgebungsvariable, etwa WINGO_UI_API_KEY, und exportier diese Variable in der Shell, die Codex startet. Codex schickt ihren Wert als Bearer-Token im Authorization-Header, der Key selbst steht also nie in der Config-Datei. ### Warum sieht Codex meinen MCP-Server nicht? Meist steht der Server in .codex/config.toml eines Projekts, dem Codex nicht vertraut, oder Codex wurde nach der Änderung nicht neu gestartet. Führ codex mcp list im Projektordner aus: Fehlt der Server dort, liest Codex die Datei nicht. ### Liest Codex die AGENTS.md aus meinem Home-Ordner? Ja. Codex liest zuerst ~/.codex/AGENTS.md, dann die AGENTS.md-Dateien vom Projektstamm bis zum aktuellen Ordner, und fügt sie standardmäßig bis 32 KiB zusammen (project_doc_max_bytes). ### Kann Codex mit einem Free-Key Pro-Komponenten installieren? Nein. Ein Free-Key liefert den Quellcode der kostenlosen Items; Pro-Blocks wie die Settings Page liefern weiterhin Props und Doku, aber für den Quellcode und npx wingo-ui@latest add brauchst du ein Pro-Konto. --- Quelle: https://wingo-ui.com/de/blog/codex-mcp-setup-react-ui