Codex MCP einrichten: React-UI mit echten Komponenten

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 (opens in a new tab) und der Config-Referenz (opens in a new tab) 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. 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:

Schritt 1: Wie bekomme ich einen Key?

Melde die CLI einmal pro Rechner an:

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.
• Pro-Key: Dazu kommt der Quellcode aller Items, auch von Blocks wie Settings Page und 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:

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):

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 (opens in a new tab)), 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:

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

# 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:

# ~/.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:

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:

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:

<!-- wingo-ui:start v=2 -->
## 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 <slug...>`. 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.
<!-- wingo-ui:end -->

Wie Codex ihn findet, beschreibt der AGENTS.md-Guide (opens in a new tab) 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.

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 1: ein Settings-Screen aus settings-page

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/<section>.
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:

// 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 (
    <SettingsPage
      sections={["profil", "cont", "notificari"]}
      profile={profile}
      account={account}
      onSave={(section: SettingsFormSection, values: SettingsSaveValues[SettingsFormSection]) =>
        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) => <Link {...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.

Prompt 2: ein Login aus login-page

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:

// 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 (
    <LoginPage
      layout="centered"
      methods={["password", "otp"]}
      showProviders={false}
      logo={<span className="text-lg font-semibold">Harbor</span>}
      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) => <Link {...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.

Prompt 3: eine selbstgeschriebene Komponente tauschen

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:

import { Button } from "@/components/ui/button";

export function SaveButton({ saving, onSave }: { saving: boolean; onSave: () => void }) {
  return (
    <Button tone="brand" loading={saving} loadingText="Wird gespeichert" onClick={onSave}>
      Änderungen speichern
    </Button>
  );
}

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.<path>.trust_level; wir haben trust_level = "trusted" unter einer Tabelle [projects."<path>"] 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 listet jedes Tool, und die Doku zu Coding 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. Alles, was wir für Coding Agents liefern, steht auf einer Seite, Wingo UI für KI-Agenten. Weitere Setups wie dieses findest du unter UI mit KI-Agenten bauen, darunter das Claude Code shadcn MCP Setup (auf Englisch) für dieselbe Aufgabe in Claude Code.

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.