codex-mcp

Ein unabhängiges, rein lesendes Qualitäts-Gate für QA-Artefakte.

codex-mcp ist ein eigenständiger MCP-Server, der Codex als kritischen zweiten Reviewer über Kandidaten für Testfälle und Bug-Findings laufen lässt — bevor der Autoren-Agent seinen Abschlussbericht schreibt. Codex inspiziert das Repository selbst, bildet sich seine eigene Sicht darauf, was abgedeckt sein sollte oder ob ein Defekt echt ist, und erst dann vergleicht es das mit dem Kandidaten, den es vorgelegt bekommen hat.

Es liefert ein Review-Delta. Es schreibt niemals dein Artefakt.

Authoring agent (Claude, or any MCP client)
        │  gathers the requirement, reads the code, drafts candidates
        ▼
  candidate result — in memory, not yet written
        │
        ▼  codex_qualify
   codex-mcp ──► Codex (read-only sandbox, rooted at your repo)
        │           ├─ reads the code, the diff, the existing tests
        │           ├─ reads blast-radius / test-charter if present
        │           └─ reads Jira / DB / other MCPs if configured, read-only
        ▼
  review delta: accept · modify · remove · missing · evidence · limitations
        │
        ▼
Authoring agent reconciles, then writes the FINAL artifact

Inhalt · Install · Mit einem Projekt verbinden · Verwendung · Konfiguration · Evidence-Connectors · Berechtigungsgrenze · API-Vertrag · Fehlerbehebung · Testing

Warum ein zweites Modell, und warum nur Lesen

Die hier behandelte Fehlerursache ist nicht „der Agent kann keine Testfälle schreiben“. Es ist die, dass ein Agent, der seine eigene Arbeit bewertet, sich selbst zustimmt. Ein Prüfer, der den Kontext des Autors teilt, ererbt dessen blinde Flecken.

Also sind zwei Eigenschaften entscheidend:

Unabhängigkeit. Codex wird dazu angestoßen, die erwartete Abdeckung abzuleiten, bevor er den im Detail ansieht, und jede Bug-Behauptung zu falsifizieren, statt sie zu bestätigen. Würde man ihn zuerst an dem Kandidaten verankern, erhielte man einen gefälligeren Prüfer, der weniger nütze ist.

Nur Lesen. Der Reviewer läuft in Codex' read-only-Sandbox, und jedes erreichbare nachgeordnete System wird durch eine Politikschicht gefiltert, die jedes Werkzeug einstuft und alles verweigert, das verändert. Ein Qualitätstor, das du nicht gefahrlos auf ein Live-Repository richten kannst, führt niemand aus.

Beide Modelle sind nicht maßgeblich. Die Quelle der Belege sind:

requirement / runtime / code / DB / external evidence  >  model opinion

Related MCP server: tenth-man-mcp

Installation

Erfordert Node 20+ . Vier Befehle, einmal pro Maschine.

# 1. The Codex CLI. codex-mcp drives it, and it owns your credentials.
npm install -g @openai/codex@latest

# 2. codex-mcp itself.
git clone <this-repo> codex-mcp && cd codex-mcp
npm install && npm run build && npm link

# 3. Sign in. A browser opens once; that is the whole flow.
codex-mcp login

# 4. Write a config, detecting any MCP servers already on this machine.
codex-mcp init --model gpt-5.6-sol

Dann bestätigen, bevor du das Tor ihm anvertraust:

codex-mcp doctor

Jede Zeile sollte ok sein. doctor ist nur Lesen und gegen ein echtes Projekt unbedenklich — siehe Fehlerbehebung, was jeder Fehler bedeutet.

Der npm-Name codex-mcp gehört zu einem nicht verwandten Paket. Installiere es aus dem Quellcode wie oben oder veröffentliche es unter deiner eigenen Scope.

Was init macht

Es schreibt ~/.config/codex-mcp/codex-mcp.yaml und, neben einer .env, wenn es Downstream-MCP-Server an üblichen Orten findet:

$ codex-mcp init --dry-run
Would write into /home/you/.config/codex-mcp
  codex-mcp.yaml  (new)
  .env            (new)

Detected:
  jira-mcp (jira) -> /home/you/jira-mcp/src/index.js
  db-mcp (database) -> /home/you/db-mcp/dist/index.js

Erkannte Server werden als Connector-Einträge geschrieben, die du aktivieren kannst; ihre Pfade liegen in .env, damit die YAML zwischen Maschinen portabel bleibt. --force überschreibt; ohne sie erstehen vorhandene Dateien bleiben.

init ist der einzige Befehl, der irgendetwas schreibt, und er rennt, bevor ein Review existiert. Reviews selbst sind streng nur Lesen.

Lieber Konfiguration selbst schreiben? Kopiere codex-mcp.example.yaml nach ~/.config/codex-mcp/codex-mcp.yaml — jeder Wert darin ist mit Kommentar und ist die eingebaute Vorgabe, es sei denn, der Kommentar es etwas anderes.

Authentifizierung

Ein Befehl, einmal pro Maschine:

codex-mcp login          # browser opens; sign in to ChatGPT
codex-mcp auth-status    # confirm

Anmeldedaten landen im eigenen Speicher der Codex-CLI (~/.codex/auth.json, Modus 0600), von ihr sie auch refresht werden. Sie Persistieren über Reboots und Terminals hinweg — du musst dich nicht pro Projekt oder pro Sitzung erneut anmelden.

codex-mcp behandelt die Anmeldedaten selbst nie direkt. Es hat keinen OAuth-Client, keinen Callback-Token-Speicher. Es ruft außen codex login status auf und liest ja/nein. Nothing, in this Context, at a review Browser opens keinen: Ein nicht authentifizierter Aufruf geht stattdessen schnell fehl.

{ "code": "CODEX_AUTH_REQUIRED", "message": "Codex is not authenticated. Run `codex-mcp login`." }

Stattdessen einen API-Schlüssel verwenden

codex-mcp login --mode api                    # hidden prompt
printenv OPENAI_API_KEY | codex-mcp login --mode api

Der Schlüssel wird aus --api-key gelesen, dann aus OPENAI_API_KEY, dann aus einer versteckten Eingabeaufforderung, und über den stdin nach codex login --with-api-key geleitet — niemals als argv-Wert, damit er nicht in deiner Prozessliste oder Shell-Historie landet. Die Codex-CLI speichert ihn; codex-mcp nicht.

Setze in deiner Konfiguration auth.mode entsprechend. Wenn die CLI in einem anderen Modus aufgemacht ist als die Konfiguration behauptet, brechen Reviews mit einen klaren Fehler ab, anstatt still das falsche Konto zu belasten.

Mit einem Projekt verbinden

Wähle eine dieser Optionen. Bist du zweimal registriert, ist das der häufigste Setup-Fehler — siehe Warnung unten.

Option A — ein Projekt, committet

Erstelle .mcp.json im root-Verzeichnis on des Projekts — nicht in .claude/, das einen anderen Satz Dateien enthält und ignorierst:

{
  "mcpServers": {
    "codex-mcp": { "command": "codex-mcp", "args": ["start"] }
  }
}

Commiten. Jedes Teammitglied, das Installation ausgeführt hat, hat jetzt das Gate — mit seiner eigenen Modellwahl aus der eigenen Konfiguration.

Option B — alle deine Projekte, nicht committet

claude mcp add codex-mcp -- codex-mcp start

Das schreibt in ~/.claude.json und gilt wo du auch arbeitest.

Nur an einer Stelle registrieren. claude mcp add schreibt in lokalem Scope, und das überstimmt .mcp.json. Wenn beide vorhanden sind, wird die Projektdatei — einschließlich eines enthaltenen env — still ignoriert. Führe claude mcp remove codex-mcp aus, wenn du zu .mcp.json wechselst.

Starte Claude Code neu. /mcp sollte jetzt codex-mcp mit drei Tools listen. Falls nicht, siehe Fehlerbehebung.

Andere MCP-Clients nehmen dieselben zwei Felder entgegen — command: codex-mcp, args: ["start"] — in welcher Konfigdatei sie auch sind.

Verwendung

Automatisch laufen lassen

Füge deiner CLAUDE.md im Projekt eine Regel hinzu. Das ist die gesamte Integrationsfläche — es gibt keine projektspezifische Codex-Logik irgendwo:

## Independent QA qualification

Before finalizing test cases or bug reports, send the complete candidate result,
project root, task/requirement context, and any available blast-radius or
test-charter to codex-mcp for independent qualification.

Reconciling means verifying each objection against the evidence it cites — not
accepting it. Apply what the evidence supports. Reject what it does not, and note
why. codex-mcp is a second opinion, not an approver.

One pass is normal. Run a second only if the first forced substantial high-risk
changes.

Damit schreibst du deine normale Anfrage und das Gate läuft selbst:

Erstelle Testfälle für DEV-2951.

Der Agent sammelt die Anforderung, liest den Code, entwirft Kandidaten, ruft codex_qualify auf, findet den Unterschied und schreibt dann den Bericht.

Ausdrücklich anfragen

Wenn es keine Regel gibt, ode du willst dass er es mit bereits Entworfenen macht:

Bevor du den Bericht schreibst, sende diese Testfälle an codex-mcp mit project.root gesetzt nach /path/rep "/path/to/repo" und task.id DEV-2951. Zeige mir, wogegen er etwas einzuwenden hat und ob du zustimmst der Zustimmung, danach schreib die endgültige Version.

Lass die Bug-Findings, that du gerade hast, durch codex_qualify laufen mit reviewType: "bugs". Wenn er etwas als false false meldet, beprüfe den Code, das es is einmal zitiert, bevor du den Finding verwirfst.

Qualifiziere diese gegen codex-mcp, but berichte nur Einwände, die die genannten Belege actual stands. Erzähl mir, welche du verworfen hast und warum.

Nützliche Varianten:

Achtung: übersetzt mit deutschem Text, aber die Befehle in Backticks unverändert.

In der dritten Spalte stand die syntax: set options.focus to "authorization and tenant isolation" etc. Also im Original stehen die Codefelder im Markdown. Ich lasse sie grade so stehen (englisch).

Die Ergebnisse lesen

Bitte deinen Agent, diese Punkte an die Oberfläche zu legen, statt still darauf zu reagieren:

• missing — die Abdeckungsteht er, du nicht. Prüfe, ob das zitierte file:line real ist.

• modify — deine Erwartung widerspricht dem Code. Für gewöhnlich das schärfste Ergebnis.

• remove — Redundant. Verifiziere, dass das, von dem item sagt, es ersetzt das deide, es wirklich ersetzt.

• limitations — was es nicht verifizieren konnte. Ein selbstsicherer Review mit langer Limitations-Liste ist ein enger Review; lies das vor dem übrigen.

• disagreements — er und dein Agent lesen dieselben Belege unterschiedlich. Diese brauchen dich, nicht das jeweils andere Modell.

Ein guter weiterer Prompt:

Sag zu jedem Einwand die Belege, die er angeführt hat, und ob du selbst nachgeprüft hast. List those up, die du verwirft hast und warum.

Was es nicht tun wird

Er editiert keine Dateien, committet nicht, pusht nichts, schreibt nicht an Jira oder die Datenbank und schreibt nicht deinen Bericht. Wenn dein Agent behauptet, codex-mcp hätte etwas geändert, dann hat er das nicht — sieh git status.

Abgleich — der Teil, auf den es ankommt

codex-mcp says dir nie, dass du annehmen sollst, was Codex sagt. Each response enthält:

{
  "reconciliation": {
    "instruction": "This is an independent second opinion, not a verdict...",
    "codexIsNotAuthoritative": true
  }
}

Codex objection
      │
      ▼
Author verifies the cited evidence
      │
      ├─ evidence supports it   → apply
      ├─ evidence does not      → reject, and record why
      └─ unclear                → investigate

Dann schreibst deren du das finale Artefakt.

Schleifenschutz

review.maxPasses (Standard 2) deckelt den Zyklus. Pass 1 ist der normale Fall; Pass 2 gibt es für Reviews, die größere, hochriskante Änderungen erzwungen haben. Eine Anfrage über das Limit abgelehnt, und meta.furtherPassesAllowed sagt dir, ob das Budget verbraucht ist. Iterieren, bis beide zwei Model identischers mas, ist nicht der Punkt — Übereinstimmung ist billig, und will she ist das, one of them aufgehört hat zu denken.

Konfiguration

Einstellungen liegen in ~/.config/codex-mcp/codex-mcp.yaml . Das ist die Datei, die du editierst. codex-mcp.example.yaml ist die kommentierte Version, mit den aktuellen Codex-Modell-IDs.

Eine fehlende Config-Datei ist voll unterstützt — der Server startet mit den Vorgaben, und das sind die sicheren Vorgaben. Verlierst du modell-Pin und jede Connector, denn Connectors können nur in YAML definiert werden.

Wo das Modell hin kommt

review:
  model: gpt-5.6-sol
  requireModel: true

Drei Ebenen können es festlegen. Die höchste gewinnt:

Keep the model in one layer. If two places, is the lower copy dead — changing it seems no effect. doctor warns if when both places and differ.

To pin a project for the whole team, add env to the .mcp.json from Option A-#option-a--one-project-committed):

{
  "mcpServers": {
    "codex-mcp": {
      "command": "codex-mcp",
      "args": ["start"],
      "env": { "CODEX_MODEL": "gpt-5.6-sol", "CODEX_REASONING_EFFORT": "high" }
    }
  }
}

Das garantiert, dass unergraduate alle denselben Reviewer verwenden, was wertvoll ist, wenn findings across the team verglichen werden. Der Preis: ein Teammitglied, dessen Codex-CLI zu alt für dieses Modell ist, bekommt einen harten CODEX_MODEL_NOT_AVAILABLE, der es aufruft, codex update zu run. Diese Fehler ist absichtlich — die Alternative is, heimlich einen schwachen Reviewer zu bekommen und dessen Urteil zu vertrauen.

Welches Modell. Bevorzugung ein Frontier-Modell. Der ganze Wert hier ist zu fangen, was der erstellende Agent übersehen hat, und ein günstigerer Reviewer yields meist basic zu mit to the method was zeig. Set requireModel: true on acommon gate, dass a change of the default does not silently change quality. Nicht verfügbares Modell raises CODEX_MODEL_NOT_AVAILABLE; codex-mcp fällt nicht auf eenes other.

Every setting, plus its environment variable

Precedence: environment > codex-mcp.yaml > defaults. The variables exist, override to one YAML value without editing the file — in .mcp.json's env, to pin project, or in the shell for a one-off.

Die Connector-Einstellungen kehren diese Rangfolge um: Die YAML gewinnt, weil sie eine explizite Absicht pro Connector darstellt und diese Variablen grobe Fallbacks für den Fall sind, dass keine YAML etwas anderes vorgibt.

Diese Schalter beziehen sich auf den Namen des Connectors, nicht seine Art — Connectors namens jira-mcp und db-mcp entsprechen weder jira noch database, fallen also beide unter CUSTOM_MCPS_ENABLED. Ein enabled: in der YAML umgeht die Frage vollständig.

Zwei Variablen haben kein YAML-Pendant, da sie gelesen werden, bevor eine Konfigurationsdatei gefunden wird: CODEX_MCP_CONFIG (Pfad zur Konfigurationsdatei) und XDG_CONFIG_HOME (wo nach ~/.config/codex-mcp/ gesucht wird).

Wo die Konfigurationsdatei gefunden wird

Der erste Treffer gewinnt:

--config <path>  →  $CODEX_MCP_CONFIG  →  ./codex-mcp.yaml  →  ~/.config/codex-mcp/codex-mcp.yaml

doctor gibt aus, welche geladen wurde. Eine .env neben der gewählten Datei wird gelesen, falls vorhanden; nichts erfordert eine. Sie lohnt sich nur für Werte, die sich pro Maschine unterscheiden — Connector-Pfade, auf die die YAML als ${JIRA_MCP_PATH} verweist — und selbst diese können stattdessen einen ${VAR:-fallback}-Standard tragen.

Setzen Sie niemals Anmeldedaten in .env oder die YAML. CHATGPT_TOKEN, SESSION_TOKEN, ACCESS_TOKEN und REFRESH_TOKEN werden vollständig ignoriert, und ihr Vorhandensein wird als Konfigurationswarnung gemeldet. Die Codex-Authentifizierung gehört zur Codex-CLI und zu Ihrem Betriebssystem-Anmeldedatenspeicher.

Evidence-Connectors

Codex spricht nie direkt mit Jira oder Ihrer Datenbank. Es verbindet sich mit dem codex-mcp-Evidence-Broker, einem separaten Nur-Lese-Prozess, der die Tools jedes nachgelagerten Servers entdeckt, klassifiziert und nur das weiterleitet, was der Richtlinie entspricht — wobei er bei jedem Aufruf erneut prüft, nicht nur bei der Entdeckung.

# ~/.config/codex-mcp/codex-mcp.yaml
connectors:
  jira-mcp:
    enabled: true
    kind: jira
    approval: once
    transport: stdio
    command: node
    args: ['/path/to/jira-mcp/src/index.js']
    cwd: /path/to/jira-mcp

  db-mcp:
    enabled: true
    kind: database
    approval: once
    transport: stdio
    command: node
    args: ['/path/to/db-mcp/dist/index.js']
    cwd: /path/to/db-mcp
    allowTools: ['execute_query']
    denyTools: ['update_query']
    maxRows: 500
    timeoutMs: 10000

kind steuert die Normalisierung auf ein stabiles Vokabular — requirement.read, database.query_readonly, testmanagement.search, external_file.read — sodass die Review-Prompt nach „der Anforderung" fragen kann, ohne zu wissen, ob Ihr Connector sie getJiraIssue oder get_jira_ticket nennt. Nicht zugeordnete Tools werden weiterhin unter ihren eigenen Namen bereitgestellt; das Hinzufügen eines neuen leseorientierten MCP erfordert keine Codeänderung.

Ein nachgelagerter Server erhält nur PATH, HOME und die env, die seine eigene Konfiguration deklariert — niemals die Prozessumgebung von codex-mcp.

Ein nicht erreichbarer Connector stuft die Review zu einer dokumentierten Einschränkung herab, statt sie fehlschlagen zu lassen. Fehlende Evidenz ist eine Tatsache über die Review, und die Antwort sagt das.

Führen Sie nach dem Hinzufügen codex-mcp doctor aus. Jede Connector-Zeile meldet, wie viele Tools bereitgestellt und wie viele durch die Richtlinie zurückgehalten wurden:

[  ok  ] Connector: jira-mcp
           4 read-only tool(s) exposed, 0 withheld by policy.
[  ok  ] Connector: db-mcp
           6 read-only tool(s) exposed, 1 withheld by policy.

Um Erlaubnis bitten — das Feld approval

Das Lesen des Projekts, das Ihnen übergeben wurde, benötigt keine Erlaubnis: Sie haben project.root angegeben, also ist das Lesen die Anfrage. Das Erreichen außerhalb davon — ein Ticket-Tracker, eine Produktionsdatenbank, ein Dateiserver — ist eine separate Entscheidung, und enabled: true in einer vor Wochen geschriebenen Konfigurationsdatei ist keine informierte Einwilligung für die heutige Review.

Die Aufforderung wird über MCP-Elicitation zugestellt, erreicht also den Menschen in Ihrem MCP-Client. Wenn Ihr Client keine Prompts anzeigen kann, wird der Connector übersprungen und in limitations dokumentiert — nicht stillschweigend erlaubt. Eine Prompt, die niemand sehen kann, ist keine Einwilligung. Setzen Sie approval: trusted auf Connectors, die Sie bereits geprüft haben.

Anforderungen

Wenn ein Connector der Art jira konfiguriert ist und task.id gesetzt ist, liest Codex das Ticket selbst und behandelt jeden Anforderungstext, den Sie übergeben haben, als Interpretation des Autoren-Agenten — eine Behauptung, die abzugleichen ist, keine Quelle. Ohne Connector fällt es auf den von Ihnen gelieferten Text zurück und dokumentiert, dass es ihn nicht unabhängig verifizieren konnte.

Datenbank

Wird nur dort herangezogen, wo sie ein Urteil ändern kann: Persistenz, Beziehungen, Mandanten-Eigentum, Zustandsübergänge, Migrationen, Datenintegrität, Verifizierung eines gemeldeten Fehlers. Die Prompt sagt das explizit, und die Richtlinienebene setzt den Rest durch.

Verwenden Sie ein Nur-Lese-Datenbankkonto. codex-mcp verweigert jede mutierende Anweisung, aber eine Nur-Lese-Berechtigung ist die Grenze, die nicht davon abhängt, dass dieser Server korrekt funktioniert.

Die Berechtigungsgrenze

Die zentrale Regel: Codex darf breit inspizieren und nichts mutieren.

Lesen Sie „breit" wörtlich — siehe Lesebereich ist weiter als das Projekt unten, bevor Sie dies auf eine Maschine richten, die Geheimnisse enthält, die Ihnen wichtig sind.

Durchsetzung, in Schichten:

1. Codex' eigene read-only-Sandbox — die primäre Grenze.

2. Befehlsrichtlinie — argv-basiert, Standard-Verweigerung. Unbekannte Binärdateien werden abgelehnt; Shell-Wrapper werden abgelehnt, weil ihre Payload nicht klassifiziert werden kann.

3. SQL-Richtlinie — Kommentare und String-Literale werden vor dem Keyword-Scan entfernt, sodass eine Mutation sich nicht in einem Anführungszeichen-Wert verstecken kann. Eine Anweisung pro Aufruf, Zeilenlimit wird eingefügt, wenn die Abfrage keines hat.

4. Tool-Richtlinie — jedes nachgelagerte MCP-Tool wird als read / write / destructive / unknown klassifiziert; nur read wird bereitgestellt. unknown wird verweigert, sofern nicht explizit auf die Whitelist gesetzt, und keine Whitelist kann ein mutierendes Tool retten — eine Grenze, über die man sich hinwegargumentieren kann, ist keine Grenze.

Der Klassifikator ist bewusst asymmetrisch: Jeder Hinweis auf Mutation schlägt jeden Hinweis auf Lesen, und ein Tool muss positiv als Nur-Lese erscheinen, um bereitgestellt zu werden. Ein Tool, das unsicher klingt, es aber nicht ist, kostet Sie eine Konfigurationszeile; ein Tool, das sicher klingt, es aber nicht ist, kostet Sie Daten.

tests/security/ behauptet all dies, einschließlich der Tatsache, dass ein abgelehnter Aufruf den nachgelagerten Server nie erreicht und dass ein Fixture-Repository nach einer Review byte-identisch ist.

Lesebereich ist weiter als das Projekt

Codex' read-only-Sandbox begrenzt Schreibvorgänge, nicht Lesevorgänge. Innerhalb davon kann Codex jede Datei lesen, die Ihr Benutzerkonto lesen kann — nicht nur Dateien unter project.root. Direkt verifiziert:

$ codex exec --sandbox read-only -C ./proj   "read ../outside.txt"
exec  sed -n '1,$p' ../outside.txt   in .../proj
      succeeded: SECRET_OUTSIDE=canary-9f3a2b

Die Codex-CLI bietet keine Option, den Lesebereich einzuschränken; sandbox_permissions gewährt nur weiteren Zugriff. Die ehrliche Aussage der Garantie lautet also:

Nichts wird modifiziert, nirgendwo. Lesevorgänge sind durch Ihre OS-Dateiberechtigungen begrenzt, nicht durch project.root.

project.root steuert, wohin der Reviewer schaut — es ist das Arbeitsverzeichnis und das Subjekt der Prompt —, aber es ist kein Lese-Gefängnis.

Was das in der Praxis bedeutet:

• Eine .env, ein privater Schlüssel oder eine Anmeldedatei, die für Ihren Benutzer lesbar ist, ist für den Reviewer erreichbar, und ihr Inhalt kann als Teil des Modellkontexts an OpenAI gesendet werden.

• Die Artefakt-Pfad-Eindämmung von codex-mcp (assertArtifactPathAllowed) verhindert, dass codex-mcp Dateien außerhalb des Projekts in die Prompt liest. Sie begrenzt nicht und kann nicht begrenzen, was Codex innerhalb seiner eigenen Sandbox liest.

• Befunde werden vor der Protokollierung redigiert, aber das ist eine Protokollierungskontrolle, keine Eindämmungskontrolle.

Wenn das für Ihre Umgebung relevant ist, führen Sie codex-mcp in einem Container oder einer VM mit nur dem eingehängten Projekt aus. Das ist heute der einzige zuverlässige Weg, Lesevorgänge zu begrenzen.

Was der Reviewer designgemäß liest

Innerhalb des Projektstamms liest es alles, einschließlich Punkt-Verzeichnissen. Das Verstecken von .claude, .cursor, .github oder einem eigenen .qa vor dem Reviewer führt dazu, dass es genau die Regeln ignoriert, die das Projekt für es niedergeschrieben hat. Bekannte Tool-Caches (.venv, .pytest_cache, .next und ähnliche) werden weiterhin aufgelistet, aber nicht als Lesematerial empfohlen.

Konventionsdateien — CLAUDE.md, AGENTS.md, CONTRIBUTING.md, TESTING.md, .cursorrules, CODEOWNERS — werden der Prompt als „zuerst lesen" präsentiert.

Der Vertrag

codex_qualify

Erforderlich: reviewType, project.root und ein Kandidatensatz, der dem Review-Typ entspricht. Alles andere ist optional und blockiert nie eine Review.

{
  "reviewType": "test-design",

  "project": { "root": "/absolute/path/to/project", "branch": "feature/DEV-123" },

  "task": {
    "id": "DEV-123",
    "source": "jira",
    "title": "Archive a resource",
    "description": "A user may archive a resource belonging to their own tenant.",
    "acceptanceCriteria": ["Archiving an active resource sets status to archived."]
  },

  "artifacts": {
    "blastRadiusPath": "docs/blast-radius.md",
    "testCharterPath": "docs/test-charter.md"
  },

  "candidate": {
    "testCases": [{ "id": "TC-001", "title": "Archive an active resource", "priority": "high" }],
    "bugs": []
  },

  "options": { "useJira": true, "useDatabase": true, "useExternalMcps": true }
}

Kandidaten reisen in der Payload. Sie wurden noch nirgendwo geschrieben, und das Erfordern einer temporären Berichtsdatei würde den Zweck zunichtemachen.

Artefaktpfade werden innerhalb von project.root aufgelöst; ein Pfad, der daraus entkommt, wird abgelehnt.

Review-Typen

Ergebnis Testdesign

{
  "status": "CHANGES_REQUIRED",
  "summary": { "accepted": 18, "modify": 2, "remove": 1, "missing": 3 },
  "accepted": ["TC-001", "TC-002"],
  "modify": [{
    "candidateId": "TC-014",
    "reason": "Expected state contradicts persistence logic.",
    "evidence": [{ "source": "code", "location": "src/session/service.ts:143" }],
    "recommendation": "Queue should remain persisted after this transition."
  }],
  "remove": [{ "candidateId": "TC-022", "reason": "Duplicates TC-018.", "supersededBy": "TC-018" }],
  "missing": [{
    "title": "Verify cross-tenant access is rejected",
    "priority": "high",
    "dimension": "authorization",
    "reason": "Target lookup accepts an externally supplied identifier.",
    "evidence": [{ "source": "code", "location": "src/resource/controller.ts:82" }]
  }],
  "disagreements": [],
  "limitations": []
}

Ergebnis Bugs

{
  "status": "CHANGES_REQUIRED",
  "summary": { "verified": 1, "falsePositive": 1, "needsMoreEvidence": 0, "other": 0 },
  "findings": [{
    "candidateId": "BUG-003",
    "verdict": "FALSE_POSITIVE",
    "confidence": "high",
    "severityAssessment": null,
    "reason": "Ownership validation occurs in router-level middleware.",
    "evidence": [
      { "source": "code", "location": "src/routes/users.ts:42" },
      { "source": "code", "location": "src/middleware/access.ts:91" }
    ],
    "recommendation": "Remove the finding unless runtime evidence contradicts the middleware."
  }],
  "limitations": []
}

status: PASS · CHANGES_REQUIRED · INCONCLUSIVE · ERROR

verdict: VERIFIED · FALSE_POSITIVE · NEEDS_MORE_EVIDENCE · SEVERITY_DISAGREEMENT · DUPLICATE_OR_ALREADY_COVERED · INCONCLUSIVE

Was der Envelope garantiert

codex-mcp normalisiert die Ausgabe des Reviewers, bevor sie zurückgegeben wird, weil ein Modell, das eine Liste bewertet, manchmal abdriften kann:

• vom Reviewer erfundene IDs werden mit einem Hinweis verworfen — man kann nicht auf einen Verweis auf einen Testfall reagieren, der nicht existiert;

• ein Kandidat, den der Reviewer nie erwähnt hat, wird als unreviewed erfasst, niemals auf „akzeptiert" hochgestuft, denn Schweigen ist keine Zustimmung;

• ein Bug ohne Verdict wird zu einem expliziten INCONCLUSIVE;

• summary-Zählwerte werden aus den Arrays neu berechnet;

• status wird aus dem Delta abgeleitet, nicht aus der Selbsteinschätzung des Reviewers.

meta.evidence berichtet, worauf das Review tatsächlich basierte — ob git-, blast-radius-, test-charter- und requirement-Zugriff verfügbar waren und welche Connectors erreichbar waren. Der Projektpfad selbst wird nie protokolliert oder zurückgegeben; meta.evidence.projectRootId ist ein Hash.

codex_auth_status

Ob Codex authentifiziert ist, in welchem Modus, und ob das mit Ihrem konfigurierten auth.mode übereinstimmt. Gibt niemals eine Anmeldeinformation zurück.

codex_capabilities

Diagnose. Welche Evidenz diese Instanz erreichen kann, welche Downstream-Tools vorenthalten wurden und warum, sowie eine explizite Liste dessen, was der Reviewer nicht tun darf.

CLI

codex-mcp init         # write ~/.config/codex-mcp/, detecting local MCP servers
codex-mcp start        # run the MCP server on stdio (what a client launches)
codex-mcp login        # authenticate (--mode chatgpt|api)
codex-mcp auth-status  # report auth state, never credentials
codex-mcp doctor       # diagnose everything; mutates nothing

init akzeptiert --model <id>, --force und --dry-run. start und doctor akzeptieren --config <path>. doctor akzeptiert außerdem --project <path> und --json.

codex-mcp broker ist intern — der Evidenz-Broker, den Codex startet. Sie führen ihn nicht von Hand aus.

Fehlerbehebung

Alles, was doctor meldet, ist entweder ok, warn (funktioniert, aber lockerer als es sein sollte) oder FAIL (Reviews können nicht funktionieren).

Fehler

Stabile Codes, sicher für Verzweigungen. Payloads werden redigiert, bevor sie den Prozess verlassen.

CODEX_AUTH_REQUIRED              CODEX_NOT_INSTALLED
CODEX_MODEL_NOT_CONFIGURED       CODEX_MODEL_NOT_AVAILABLE
INVALID_PROJECT_ROOT             PROJECT_ACCESS_DENIED
INVALID_REVIEW_REQUEST           INVALID_REVIEW_TYPE
DOWNSTREAM_MCP_UNAVAILABLE       DOWNSTREAM_MCP_PERMISSION_DENIED
DB_QUERY_DENIED                  DB_QUERY_TIMEOUT
CODEX_EXECUTION_FAILED           CODEX_OUTPUT_INVALID
REVIEW_TIMEOUT                   INTERNAL_ERROR

Wenn Codex eine Ausgabe zurückgibt, die nicht zum Schema passt, versucht codex-mcp es einmal mit einer expliziten Korrektur, die eine erneute Analyse verbietet. Schlägt auch das fehl, wird CODEX_OUTPUT_INVALID zurückgegeben. Es wird kein teilweise geparstes Review zurückgegeben — Sie würden darauf reagieren.

Beobachtbarkeit

Strukturiertes JSON auf stderr (stdout gehört zum MCP-Transport). Protokolliert werden: Review-ID und -Typ, gehashte Projekt-ID, Modell, Zeitmessungen, Connector-Verfügbarkeit, Kandidatenanzahl, Codex-Exit-Status, Schema-Validierungsstatus.

Nie protokolliert: Tokens, Passwörter, DB-Anmeldeinformationen, Cookies, im Quellcode gefundene Geheimnisse. Die Redaktion läuft auf jeder Ebene, einschließlich debug.

Tests

Fünf Ebenen, die günstigste zuerst. Arbeiten Sie sie der Reihe nach ab — ein Fehler auf einer Ebene macht das Ergebnis der nächsten Ebene bedeutungslos.

1. Automatisierte Suite — kostenlos, offline, ~7s

npm install
npm run build
npm test
npm run typecheck

400+ Tests gegen eine Fake-Codex-CLI und einen absichtlich feindseligen Fake-MCP-Server. Kein Netzwerk, keine Modellaufrufe, deterministisch. Das führen Sie bei jeder Änderung und in CI aus.

tests/security/ ist der Teil, der sich zu lesen lohnt: Er stellt sicher, dass Dateibearbeitungen, Commits, Pushes, Issue-Schreibvorgänge und DB-Mutationen verweigert werden — und dass ein verweigerter Aufruf den Downstream-Server nie erreicht.

2. doctor — ist diese Installation korrekt verdrahtet

codex-mcp doctor
codex-mcp doctor --project /path/to/repo

Nur lesend, sicher gegen ein Live-Projekt. Prüft Node, die Codex-CLI, Authentifizierung, Auth-Modus-Übereinstimmung, Modell, Sandbox, Konfigurationsdatei und jeden konfigurierten Connector.

3. codex_capabilities — welche Evidenz kann es tatsächlich erreichen

doctor liefert Zählwerte; dies liefert die Aufschlüsselung pro Tool, einschließlich warum jedes vorenthaltene Tool vorenthalten wurde. Rufen Sie es von Ihrem MCP-Client auf, oder:

node -e "
import('./dist/src/config/config.js').then(async ({loadConfig}) => {
  const {CodexMcpServer} = await import('./dist/src/server.js');
  const {Logger} = await import('./dist/src/util/logger.js');
  const s = new CodexMcpServer({config: loadConfig(), logger: new Logger('error', {}, {write(){}})});
  console.log(JSON.stringify(await s.callToolForTesting('codex_capabilities', {}), null, 2));
  process.exit(0);
});"

Prüfen Sie, dass die erwarteten Tools in allowedTools sind, und dass jeder Eintrag in deniedTools einer ist, den Sie verweigert haben möchten. Ein Nur-Lese-Tool mit ungewöhnlichem Namen landet in deniedTools als unknown — fügen Sie es zu allowTools dieses Connectors hinzu.

4. npm run try — ein echtes Review, echtes Modell, echte Kosten

Dies ist die einzige Ebene, die Budget verbraucht. Sie beweist den gesamten Pfad: Authentifizierung, Modell, Sandbox, Evidenzerfassung, Connectors, Prompt, strukturierte Ausgabe.

npm run try -- --project /path/to/repo
npm run try -- --project /path/to/repo --type bugs
npm run try -- --project /path/to/repo --type combined --task DEV-123
npm run try -- --project /path/to/repo --candidates ./candidates.json --json

Ohne --candidates sendet es einen Satz, der mit bekannten Fehlern angereichert ist — zwei Duplikate, eine Assertion, der der Code widerspricht, und mehrere offensichtliche Lücken. Das ist der Punkt: Sie testen den Reviewer, also verwenden Sie Eingaben, deren korrekte Antwort Sie bereits kennen.

Bewerten Sie es danach:

• hat es das Duplikat in remove gesetzt?

• hat es die widersprochene Assertion in modify gesetzt, mit Verweis auf den Code?

• hat jeder missing-Eintrag eine echte file:line, keine vage Angabe?

• ist das Repository danach unverändert (git status)?

Ein PASS auf dem angereicherten Satz bedeutet, dass etwas falsch ist, nicht dass Ihr Code sauber ist.

Liefern Sie --candidates mit Ihrem eigenen JSON, um einen echten Workflow zu proben:

{ "testCases": [{ "id": "TC-1", "title": "..." }], "bugs": [] }

5. End-to-End-Fixture — opt-in

CODEX_MCP_E2E=1 npm test -- tests/e2e

Erstellt ein Fixture-Repository mit einer echten Abdeckungslücke (Idempotenz) und einem Bug-Report, den die Router-Middleware bereits widerlegt, führt eine vollständige Qualifizierung gegen die echte Codex-CLI aus und stellt sicher, dass das Fixture danach byte-identisch ist. Dauert ein paar Minuten.

Als MCP-Server betreiben

Sobald die obigen Ebenen bestanden sind, betreiben Sie es so, wie es ein Client tun wird:

printf '%s\n%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | codex-mcp start

Dann registrieren Sie es in Claude Code und verwenden es auf einem echten Ticket.

Entwicklung

src/
  config/      resolution, precedence, validation
  auth/        Codex CLI delegation for both auth modes
  codex/       process spawning, argv construction, output parsing
  review/      orchestration, per-type reviewers, output normalization
  evidence/    repository, git, artifacts, requirement, database, external
  mcp-broker/  downstream clients, discovery, classification, the broker server
  policy/      command, SQL, MCP-tool, permission, and consent decisions
  prompts/     base reviewer, test-design, bug-review
  schemas/     public request and result contracts
  tools/       the three MCP tools

Lizenz

MIT