codex-mcp

An independent, read-only quality gate for QA artifacts.

codex-mcp is a standalone MCP server that runs Codex as an adversarial second reviewer over candidate test cases and bug findings — before the authoring agent writes its final report. Codex inspects the repository itself, forms its own view of what should be covered or whether a defect is real, and only then compares that against the candidate it was given.

It returns a review delta. It never writes your artifact.

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

Contents · Install · Connect to a project · Use it · Configuration · Evidence connectors · GitHub · Permission boundary · API contract · Troubleshooting · Testing

Why a second model, and why read-only

The failure mode this addresses is not "the agent cannot write test cases". It is that an agent grading its own work agrees with itself. A reviewer that shares the author's context inherits the author's blind spots.

So two properties are load-bearing:

Independence. Codex is prompted to derive expected coverage before it looks closely at the candidate, and to try to falsify each bug claim rather than confirm it. Anchoring it on the candidate first would produce a more agreeable reviewer and a less useful one.

Read-only. The reviewer runs in Codex's read-only sandbox, and every downstream system it can reach is filtered through a policy layer that classifies each tool and refuses anything that mutates. A quality gate you cannot safely point at a live repository is a quality gate nobody runs.

Neither model is authoritative. Source evidence is:

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

Related MCP server: Loopbreaker

Install

Requires Node 20+ on Linux, macOS, or Windows. Four commands, once per machine — identical on all three.

# 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

Then confirm before trusting it:

codex-mcp doctor

Every line should read ok. doctor is read-only and safe against a live project — see Troubleshooting for what each failure means.

The npm name codex-mcp belongs to an unrelated package. Install from source as above, or publish under your own scope.

Windows

Nothing extra to configure — the commands above are the whole setup. Worth knowing why, because the failure it avoids is a confusing one.

npm does not install a codex.exe. It installs codex.cmd (plus a .ps1 and an extensionless shell script), and Windows resolves the .cmd through PATHEXT — something cmd.exe does but CreateProcess, which Node's spawn uses, does not. A bare codex therefore fails with spawn codex ENOENT even though codex --version works in your terminal, and since CVE-2024-27980 Node will not run a .cmd without a shell either. doctor used to read this as a missing CLI and tell you to reinstall, which never helped.

codex-mcp now resolves the launcher itself and passes arguments through cmd.exe with quoting that survives the shim's double parse, so a project path containing & or a connector env value containing | reaches Codex intact. POSIX is untouched: the resolver returns immediately off Windows.

CODEX_BINARY also accepts a script rather than an installed CLI — its shebang is honoured on Windows, where the OS would otherwise refuse the file.

What init does

It writes ~/.config/codex-mcp/codex-mcp.yaml, and a .env beside it if it found downstream MCP servers in conventional locations:

$ 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

Detected servers are written as connector entries you can enable, with their paths kept in .env so the YAML stays portable across machines. --force overwrites; without it, existing files are kept.

init is the only command that writes anything, and it runs before any review exists. Reviews themselves are strictly read-only.

Prefer to write the config yourself? Copy codex-mcp.example.yaml to ~/.config/codex-mcp/codex-mcp.yaml — every value in it is annotated and is the built-in default unless its comment says otherwise.

Authentication

One command, once per machine:

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

Credentials land in the Codex CLI's own store (~/.codex/auth.json, mode 0600) and are refreshed by it. They persist across reboots and terminals — you do not log in again per project or per session.

codex-mcp never handles the credential itself. It has no OAuth client, no callback listener, no token storage. It shells out to codex login status and reads yes/no. Nothing here can open a browser during a review: an unauthenticated call fails fast instead.

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

Using an API key instead

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

The key is read from --api-key, then OPENAI_API_KEY, then a hidden prompt, and piped to codex login --with-api-key over stdin — never an argv element, so it stays out of your process table and shell history. The Codex CLI stores it; codex-mcp does not.

Set auth.mode in your config to match. If the CLI is authenticated in a different mode than the config claims, reviews fail with a clear error rather than silently billing the wrong account.

Connect to a project

Pick one of these. Registering twice is the most common setup mistake — see the warning below.

Option A — one project, committed

Create .mcp.json in the project root — not .claude/, which holds a different set of files and will ignore it:

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

Commit it. Every teammate who has run Install now has the gate, using their own model choice from their own config.

Option B — all your projects, not committed

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

This writes to ~/.claude.json and applies wherever you work.

Register in one place only. claude mcp add writes at local scope, which outranks .mcp.json. With both present, the project file — including any env in it — is silently ignored. Run claude mcp remove codex-mcp if you are switching to .mcp.json.

Restart Claude Code. /mcp should now list codex-mcp with four tools. If it does not, see Troubleshooting.

Other MCP clients take the same two fields — command: codex-mcp, args: ["start"] — in whatever config file they use.

Use it

Make it automatic

Add one rule to the project's CLAUDE.md. This is the entire integration surface — no project-specific Codex logic anywhere:

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

With that in place you write your normal request and the gate runs itself:

Create test cases for DEV-2951.

The agent gathers the requirement, reads the code, drafts candidates, calls codex_qualify, reconciles, then writes the report.

Ask for it explicitly

When there is no rule, or you want it on something already drafted:

Before you write the report, send these test cases to codex-mcp with project.root set to /path/to/repo and task.id DEV-2951. Show me what it objects to and whether you agree, then write the final version.

Run the bug findings you just wrote through codex_qualify with reviewType: "bugs". For anything it calls a false positive, check the code it cites before you drop the finding.

Qualify these against codex-mcp, but only report objections where the cited evidence actually holds up. Tell me which ones you rejected and why.

Useful variations:

Reading what comes back

Ask your agent to surface these rather than silently acting on them:

• missing — coverage it says you lack. Check the cited file:line is real.

• modify — your expectation contradicts the code. Usually the sharpest finding.

• remove — redundant. Verify the thing it says supersedes yours actually does.

• limitations — what it could not verify. A confident review with a long limitations list is a narrow review; read this before trusting the rest.

• disagreements — it and your agent read the same evidence differently. These need you, not either model.

A good follow-up prompt:

For each objection, tell me the evidence it cited and whether you verified it yourself. List anything you rejected and why.

What it will not do

It never edits files, commits, pushes, writes to Jira or the database, or writes your report. If your agent claims codex-mcp changed something, it did not — check git status.

Reconciliation — the part that matters

codex-mcp never tells you to accept Codex. Every response carries:

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

Then you write the final artifact.

Loop protection

There is no multi-turn handshake between the reviewer and the authoring agent. One codex_qualify call is one independent review returning one structured delta; reconciliation happens on your side.

review.maxPasses defaults to 1. A second pass carries no record of the first — no previous findings, no author responses, no revised candidate — so it is not a continuation, it is the same review run twice at full cost. Raising the limit is supported and will work; it just buys repeated work rather than progress. A request above the limit is refused, and meta.furtherPassesAllowed reports the budget.

Real multi-pass review needs a continuation contract carrying reviewId, previousFindings, authorResponses, and revisedCandidate. That is deferred; see Limitations.

Iterating until the two models agree is not the goal in any case — agreement is cheap, and reaching it usually means one of them stopped thinking.

Configuration

Settings live in ~/.config/codex-mcp/codex-mcp.yaml. That is the one file to edit. codex-mcp.example.yaml is the annotated version, with the current Codex model ids.

An absent config file is fully supported — the server starts on defaults, which are the safe ones. What you lose is the model pin and every connector, since connectors can only be defined in YAML.

Where the model goes

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

Three layers can set it. Highest wins:

Keep the model in one layer. A key set in two places makes the lower copy dead — editing it appears to do nothing. doctor warns when the model is set in both and the two disagree.

To pin a project for a whole team, add env to the .mcp.json from Option A:

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

That guarantees everyone gets the same reviewer, which is worth a lot when findings are compared across a team. The cost: a teammate whose Codex CLI is too old for that model gets a hard CODEX_MODEL_NOT_AVAILABLE telling them to run codex update. That failure is deliberate — the alternative is them quietly getting a weaker reviewer and trusting its verdict.

Which model. Prefer a frontier model. The entire value here is catching what the authoring agent missed, and a cheaper reviewer mostly agrees with whatever it is shown. Set requireModel: true on a shared gate so a change to the Codex default cannot quietly alter review quality. An unavailable model raises CODEX_MODEL_NOT_AVAILABLE; codex-mcp will not fall back to another one.

Every setting, and its environment variable

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

Connector settings invert that precedence: the YAML wins, because it is explicit per-connector intent and these variables are coarse fallbacks for when no YAML says otherwise.

Those toggles match the connector's name, not its kind — connectors called jira-mcp and db-mcp match neither jira nor database, so both fall under CUSTOM_MCPS_ENABLED. Setting enabled: in the YAML avoids the question entirely.

Two variables have no YAML equivalent, since they are read before any config file is located: CODEX_MCP_CONFIG (path to the config file) and XDG_CONFIG_HOME (where ~/.config/codex-mcp/ is looked for).

Where the config file is found

First hit wins:

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

doctor prints which one it loaded. A .env beside the chosen file is read if present; nothing requires one. It is worth having only for values that differ per machine — connector paths the YAML references as ${JIRA_MCP_PATH} — and even those can carry a ${VAR:-fallback} default instead.

Never put credentials in .env or the YAML. CHATGPT_TOKEN, SESSION_TOKEN, ACCESS_TOKEN, and REFRESH_TOKEN are ignored outright, and their presence is reported as a configuration warning. Codex authentication belongs to the Codex CLI and your OS credential store.

Evidence connectors

Codex never talks to Jira or your database directly. It connects to the codex-mcp evidence broker, a separate read-only process that discovers each downstream server's tools, classifies them, and forwards only what passes policy — re-checking on every call, not just at discovery.

A connector launches a downstream MCP server, so setting one up is two decisions: which server to launch, and how it gets its credentials. Those are independent, and the second one has two answers.

A — a published server, credentials in the connector

For a server you run straight from npm and configure through the environment. The env block is the whole configuration:

# ~/.config/codex-mcp/codex-mcp.yaml
connectors:
  jira:
    enabled: true
    kind: jira
    approval: once
    transport: stdio
    command: npx
    args: ['-y', 'your-jira-mcp-server']
    env:
      JIRA_BASE_URL: https://your-org.atlassian.net
      JIRA_EMAIL: you@your-org.com
      JIRA_API_TOKEN: ${JIRA_API_TOKEN}    # from the .env beside this file

  database:
    enabled: true
    kind: database
    approval: once
    transport: stdio
    command: npx
    args: ['-y', 'your-db-mcp-server']
    env:
      DB_DIALECT: mysql
      DB_HOST: db.internal
      DB_PORT: '3306'                      # every value must be a string
      DB_USERNAME: qa_readonly
      DB_PASSWORD: ${DB_PASSWORD}
    allowTools: ['execute_query']
    denyTools: ['update_query']
    maxRows: 500

env is passed through untouched — codex-mcp never reads these keys, so they have to match what your server expects. DB_* is a common spelling, not a schema: a MySQL-specific server that reads MYSQL_HOST will ignore DB_HOST, and one that wants a single DSN wants DATABASE_URL instead. Check the server's own README first. Splitting the connection into parts is worth it where the server supports it — the password stays one isolated ${VAR} instead of being buried in a URL that is awkward to redact and easy to paste somewhere public.

A GitHub connector belongs in this shape too — see GitHub below.

Write the secret as a ${VAR} reference rather than a literal. It resolves from the .env beside the config or from the environment, an unset one is reported by doctor instead of failing at review time, and ${VAR:-fallback} supplies a default. This config file is the one people commit or share; keep it free of anything you would not paste into a pull request.

B — a server you already have, credentials in that project

For an MCP server checked out locally and already working with your editor. Point at its entrypoint, set cwd, and omit env entirely — servers of this shape load their own .env on startup:

connectors:
  jira:
    enabled: true
    kind: jira
    approval: once
    transport: stdio
    command: node
    args: ['/path/to/jira-mcp/src/index.js']
    cwd: /path/to/jira-mcp
    denyTools: ['create_jira_ticket', 'update_jira_ticket']

  database:
    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']
    maxRows: 500
    timeoutMs: 10000

Prefer B when you have the choice. No credential enters codex-mcp's config at all, and the server keeps one set of credentials whether codex-mcp drives it or your editor does — rotate the token in one place and both follow.

Check how the server finds its .env before relying on this. One that resolves against its own file (resolve(__dirname, '../.env')) works regardless of cwd; one that reads the working directory needs cwd set to its project root, which is the case worth setting cwd for even when it looks redundant.

If the database server can reach more than one database, point the connector at the narrowest one. The reviewer picks its own connection per call, so a server that can see production is one prompt away from querying it.

kind drives normalization onto a stable vocabulary — requirement.read, database.query_readonly, testmanagement.search, external_file.read — so the reviewer prompt can ask for "the requirement" without knowing whether your connector calls it getJiraIssue or get_jira_ticket. Unmapped tools are still exposed under their own names; adding a new read-oriented MCP requires no code change.

A downstream server receives only PATH, HOME, and the env its own config declares — never the codex-mcp process environment.

An unreachable connector degrades the review to a recorded limitation rather than failing it. Missing evidence is a fact about the review, and the response says so.

Run codex-mcp doctor after adding one. Each connector line is labelled with the key you gave it, and reports how many tools were exposed and how many were withheld by policy:

[  ok  ] Connector: jira
           3 read-only tool(s) exposed, 2 withheld by policy.
[  ok  ] Connector: database
           6 read-only tool(s) exposed, 1 withheld by policy.

The withheld counts are the denyTools from the samples above — the two Jira writes and update_query. A count higher than your denyTools list means the classifier withheld something on its own; codex_capabilities names which.

Asking permission — the approval field

Reading the project you were handed needs no permission: you supplied project.root, so reading it is the request. Reaching outside it — a ticket tracker, a production database, a file server — is a separate decision, and enabled: true in a config file written weeks ago is not informed consent for today's review.

The prompt is delivered through MCP elicitation, so it reaches the human in your MCP client. If your client cannot show prompts, the connector is skipped and recorded in limitations — not silently allowed. A prompt nobody can see is not consent. Set approval: trusted on connectors you have already vetted.

Requirements

When a jira-kind connector is configured and task.id is set, Codex reads the ticket itself and treats any requirement text you passed as the authoring agent's interpretation — a claim to reconcile, not a source. Without a connector it falls back to the text you supplied and records that it could not verify it independently.

Database

Consulted only where it can change a verdict: persistence, relationships, tenant ownership, state transitions, migrations, data integrity, verifying a reported defect. The prompt says so explicitly, and the policy layer enforces the rest.

Use a read-only database account. codex-mcp refuses every mutating statement, but a read-only grant is the boundary that does not depend on this server being correct.

GitHub

Issues, pull requests, and repository contents, brokered like any other connector. Configure it as style A — gh already holds a credential, so there is nothing new to create:

connectors:
  github:
    enabled: true
    kind: custom
    approval: once
    transport: stdio
    command: npx
    args: ['-y', '@modelcontextprotocol/server-github']
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_TOKEN}

GITHUB_TOKEN=$(gh auth token) codex-mcp doctor

command is not gh. This field launches an MCP server and the gh CLI does not speak MCP — it would fail the handshake. gh mints the token; the server does the talking.

The classifier sorts the tools by name, with no GitHub-specific rules:

[  ok  ] Connector: github
           14 read-only tool(s) exposed, 12 withheld by policy.

Exposed: get_issue, list_issues, search_issues, get_file_contents, search_code, list_commits, and the pull-request reads. Withheld tools are refused at call time, not merely hidden — github__create_issue comes back DOWNSTREAM_MCP_PERMISSION_DENIED.

get_file_contents and search_code read a repository without a clone, which is useful for a dependency you do not have checked out. It is not a substitute for project.root: a review still needs the working tree, the diff, and the existing tests. See Reviewing a GitHub repository.

Set kind: jira instead of custom if you track requirements as GitHub issues and want task.id resolved through it — that is what makes the reviewer read the issue itself rather than trusting the description your agent passed in.

A caveat on doctor: the GitHub MCP server lists its tools without checking the token, so a connector with GITHUB_TOKEN unset still reports ok with the full count. Calls then fail with 401. The Configuration warning naming the unset variable is the real signal.

Prefer a read-scoped token, and see Why not just let it run gh for what goes wrong if you skip the broker and hand Codex the CLI directly.

Project memory

A Codex run is stateless: it cannot remember what a previous review of the same project established, so every review would otherwise rediscover the same business rules and ownership paths from scratch.

The server remembers instead. The reviewer proposes durable facts in a projectMemory array; codex-mcp screens and stores them, and hands the relevant ones to the next review as evidence.

~/.local/state/codex-mcp/          (or $XDG_STATE_HOME/codex-mcp)
└── projects/
    └── <projectRootId>/
        └── memory.json

The id is the same hash reported as meta.evidence.projectRootId, so a stored file and a review result correlate without either recording the path.

Three things keep this from becoming a liability:

• Nothing is written to your project. The store lives in codex-mcp's own state directory. The read-only guarantee is about your repository and your external systems; it was never a claim that the server keeps no state.

• Nothing is written from inside the sandbox. Codex still cannot write anywhere. Persistence happens in the server process, after the review returns, from data that already passed schema validation.

• Facts are screened before they are kept. A proposed fact is rejected if it carries no evidence, if it reads like a credential or secret, or if it is hedged — might, appears to, unverified. Only settled knowledge is stored.

A fact several reviews independently assert gets a confirmation count rather than a duplicate entry, and stored facts are handed back to the reviewer as evidence at the same level as a derived artifact: useful, and still checkable. Where the code now contradicts one, the code wins.

Writes are atomic — written to a temporary file and renamed — so an interrupted write leaves the previous store intact rather than a truncated file that reads as "nothing remembered". A store that cannot be read or written degrades to empty; memory is an optimization, and failing a review over it would be the wrong trade.

Turn it off with memory.enabled: false if you want the server to hold nothing between reviews. To clear one project, delete its directory under projects/.

The invariant this preserves, stated exactly:

Qualification never modifies the target project or any connected source system. codex-mcp writes only to its own config and state directories.

Reviewing a GitHub repository

codex-mcp reviews a working copy on disk, not a URL. There is no "paste a repo link" mode, and that is deliberate — the reviewer reads the code, the diff, the existing tests, and the project's own conventions, which means it needs the files. Point it at a clone.

A whole repository

git clone git@github.com:your-org/your-repo.git
cd your-repo

Then ask your agent, with the absolute path:

Draft test cases for the checkout flow, then qualify them with codex-mcp using project.root /home/you/your-repo.

If .mcp.json lives in that repo, project.root is just the repo you already have open.

A pull request

Check the PR branch out locally and tell codex-mcp what to diff against:

gh pr checkout 482          # or: git fetch origin pull/482/head:pr-482 && git switch pr-482

{
  "reviewType": "combined",
  "project": { "root": "/home/you/your-repo", "branch": "origin/main" },
  "task": { "id": "DEV-2951", "source": "jira", "title": "Archive a resource" },
  "candidate": { "testCases": [], "bugs": [] }
}

project.branch is the base ref, not the branch under review. The reviewer always reads the checked-out tree; this tells it what to compare against, and it diffs <base>...HEAD. Omit it and codex-mcp tries origin/HEAD, origin/main, origin/master, main, then master, recording a limitation if none resolve.

As a prompt:

I've checked out PR #482. Send my bug findings to codex-mcp with project.root /home/you/your-repo and project.branch origin/main, then show me what it refutes.

Run git fetch origin first on a shallow or stale clone — without the base ref present locally, the diff falls back to the working tree only and the review loses the change set.

GitHub as an evidence source

The clone gives codex-mcp the code. To also let it read issues and PR discussion, add a GitHub connector — brokered read-only like any other, with its write tools withheld by policy. The configuration and the exposed/withheld tool list live with the other connectors under GitHub; one line is all it takes to point at it:

GITHUB_TOKEN=$(gh auth token) codex-mcp doctor

What it adds here, on top of the clone: get_issue and search_issues give the reviewer the issue behind the branch, and the pull-request reads give it the review discussion — the argument about the change, which the diff does not carry. Neither replaces the working tree.

Why not just let it run gh

Codex can execute gh — it is on PATH, and the sandbox does not block the network. With a token in its environment it fetches live issues happily. Do not do this.

--sandbox read-only restricts the filesystem, not the network. A token with repo scope in that environment means gh issue create, gh pr comment, gh pr merge, and gh repo delete are all available, none of them pass through the broker, and nothing in codex-mcp can refuse them. The forbidden list codex_capabilities returns — which promises the reviewer will never "create, edit, comment on, or transition issues" — stops being true.

Brokering costs one connector entry and keeps the guarantee.

A tool with an unusual name may land in deniedTools as unknown; add it to that connector's allowTools if it is genuinely read-only.

What it does not do

• It will not clone for you, or accept https://github.com/org/repo as project.root.

• It will not post a review comment, approve a PR, or push anything. The delta comes back to your agent; you write the final artifact.

• Private submodules and LFS objects must already be fetched locally.

The permission boundary

The central rule: Codex may inspect broadly and mutate nothing.

Read "broadly" literally — see read scope below before pointing this at a machine holding secrets you care about.

Enforcement, in layers:

1. Codex's own read-only sandbox — the primary boundary.

2. Command policy — argv-based, default-deny. Unknown binaries are refused; shell wrappers are refused because their payload cannot be classified.

3. SQL policy — comments and string literals are stripped before keyword scanning, so a mutation cannot hide inside a quoted value. One statement per call, row cap injected when the query has none.

4. Tool policy — every downstream MCP tool is classified read / write / destructive / unknown; only read is exposed. unknown is denied unless explicitly allowlisted, and no allowlist can rescue a mutating tool — a boundary you can argue your way past is not a boundary.

The classifier is deliberately asymmetric: any hint of mutation beats any hint of reading, and a tool must look positively read-only to be exposed. A tool that sounds unsafe but is not costs you one line of config; a tool that sounds safe but is not costs you data.

tests/security/ asserts all of this, including that a refused call never reaches the downstream server and that a fixture repository is byte-identical after a review.

Read scope is wider than the project

Codex's read-only sandbox constrains writes, not reads. Inside it, Codex can read any file your user account can read — not only files under project.root. Verified directly:

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

The Codex CLI offers no option to narrow read scope; sandbox_permissions only grants further access. So the honest statement of the guarantee is:

Nothing is modified, anywhere. Reads are bounded by your OS file permissions, not by project.root.

project.root steers where the reviewer looks — it is the working directory and the subject of the prompt — but it is not a read jail.

What this means in practice:

• A .env, private key, or credentials file anywhere readable by your user is reachable by the reviewer, and its contents may be sent to OpenAI as part of the model's context.

• codex-mcp's own artifact-path containment (assertArtifactPathAllowed) stops codex-mcp from reading files outside the project into the prompt. It does not and cannot constrain what Codex reads inside its own sandbox.

• Findings are redacted before they are logged, but that is a logging control, not a containment one.

If that matters for your environment, run codex-mcp inside a container or VM with only the project mounted. That is the only reliable way to bound reads today.

What the reviewer reads by design

Within the project root it reads everything, including dot-directories. Hiding .claude, .cursor, .github, or a team's own .qa from the reviewer is how it ends up ignoring the very rules the project wrote down for it. Known tool caches (.venv, .pytest_cache, .next, and the like) are still listed but are not recommended to it as reading material.

Convention files — CLAUDE.md, AGENTS.md, CONTRIBUTING.md, TESTING.md, .cursorrules, CODEOWNERS — are surfaced to the prompt as "read these first".

The contract

codex_qualify

Required: reviewType, project.root, and a candidate set matching the review type. Everything else is optional and never blocks a review.

{
  "reviewType": "test-design",

  "project": { "root": "/absolute/path/to/project", "branch": "origin/main" },

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

Candidates travel in the payload. They have not been written anywhere yet, and requiring a temporary report file would defeat the point.

Artifact paths are resolved inside project.root; a path escaping it is refused.

Review types

Test-design result

{
  "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": []
}

Bug result

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

status is computed by codex-mcp, not reported by the model. A model asked whether its own output requires action will sometimes say no while handing back a delta that plainly does. It is derived from the content: any modify, remove, missing, or material disagreement makes it CHANGES_REQUIRED; a material limitation or an unreachable verdict makes it INCONCLUSIVE. A review with an unresolved material disagreement can never come back PASS. ERROR and INCONCLUSIVE pass through when the reviewer sets them, since those are statements about what it was able to do rather than about the delta.

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

What the envelope guarantees

codex-mcp normalizes the reviewer's output before returning it, because a model grading a list will sometimes drift:

• ids the reviewer invented are dropped, with a note — you cannot act on a reference to a test case that does not exist;

• a candidate the reviewer never mentioned is recorded as unreviewed, never promoted to accepted, because silence is not approval;

• a bug with no verdict becomes an explicit INCONCLUSIVE;

• summary counts are recomputed from the arrays;

• status is derived from the delta, not from the reviewer's self-assessment.

meta.evidence reports what the review was actually based on — whether git, blast-radius, test-charter, and requirement access were available, and which connectors were reachable. The project path itself is never logged or returned; meta.evidence.projectRootId is a hash.

codex_auth_status

Whether Codex is authenticated, in which mode, and whether that matches your configured auth.mode. Never returns a credential.

codex_capabilities

Diagnostic. What evidence this instance can reach, which downstream tools were withheld and why, and an explicit list of what the reviewer is forbidden to do.

codex_ask

Ask Codex a general question, get prose back. The only tool here that does not return a review delta.

It reads no repository. Codex is launched rooted at an empty scratch directory, so nothing about your code is in scope — that is the absence of an argument, not a rule the model is asked to follow. Ask it about your codebase and it will tell you it cannot see it. codex_qualify is the grounded path for that.

It can reach your evidence connectors, on exactly the terms a review does: each one goes through the same consent gate its approval setting drives, and a connector that is denied — or that no interactive client was available to approve — is reported in limitations and the question is answered without it.

$ codex-mcp ask "Summarise Jira ticket TASK-42 in four sentences."
TASK-42 adds an in-app notification bell, unread badge, dropdown, and
real-time SSE updates. It notifies staff of student submissions and students
of assignment reviews, with extensible notification types. It also fixes
grading authorization and submission-identity spoofing vulnerabilities.
Implementation is complete but uncommitted and remains "To Do".

[grounded in: jira, database]

The response reports what it actually had:

{ "answer": "...", "connectorsUsed": ["jira", "database"], "limitations": [] }

Treat an answer with an empty connectorsUsed as unverified recall. Even a grounded one is weaker evidence than a review's citations, which are checked against their source; the usual precedence holds either way — requirement, runtime, code, and database beat model opinion.

Consent differs by surface. From an MCP client you get the elicitation prompt, once per session per connector, shared with reviews. From the terminal, running codex-mcp ask is itself taken as consent — the human typed it — so there is no prompt. That is a deliberate weakening: anything able to invoke the CLI can reach your connectors without being asked.

Times out at 120s rather than the review path's 900s.

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 ask "..."    # a general question; no repo, but consented connectors
codex-mcp doctor       # diagnose everything; mutates nothing

init takes --model <id>, --force, and --dry-run. start and doctor take --config <path>. doctor also takes --project <path> and --json.

codex-mcp broker is internal — the evidence broker that Codex launches. You do not run it by hand.

Troubleshooting

Everything doctor reports is either ok, warn (works, but looser than it should be), or FAIL (reviews cannot work).

Errors

Stable codes, safe to branch on. Payloads are redacted before they leave the process.

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

If Codex returns output that does not match the schema, codex-mcp retries once with an explicit correction that forbids re-analysis. If that also fails it returns CODEX_OUTPUT_INVALID. It does not return a partially parsed review — you would act on it.

Observability

Structured JSON to stderr (stdout belongs to the MCP transport). Logged: review id and type, hashed project id, model, timings, connector availability, candidate counts, Codex exit status, schema-validation status.

Never logged: tokens, passwords, DB credentials, cookies, secrets found in source. Redaction runs at every level, including debug.

Testing

Five layers, cheapest first. Work down them — a failure at one layer makes the next layer's result meaningless.

1. Automated suite — free, offline, ~7s

npm install
npm run build
npm test
npm run typecheck

400+ tests against a fake Codex CLI and a deliberately hostile fake MCP server. No network, no model calls, deterministic. This is what you run on every change and in CI.

Green on Linux and macOS. On Windows the spawn and launcher layers pass, but ten tests still fail on path handling — ~ expansion, HOME-derived config discovery, and project-root containment all assume POSIX separators. Those are assertions about paths, not about behaviour under review; the server itself runs correctly on Windows.

tests/security/ is the part worth reading: it asserts that file edits, commits, pushes, issue writes, and DB mutations are refused — and that a refused call never reaches the downstream server.

2. doctor — is this install wired up correctly

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

Read-only, safe against a live project. Checks Node, the Codex CLI, auth, auth mode agreement, model, sandbox, config file, and every configured connector.

3. codex_capabilities — which evidence can it actually reach

doctor gives counts; this gives the per-tool breakdown, including why each withheld tool was withheld. Call it from your MCP client, or:

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);
});"

Check that the tools you expect are in allowedTools, and that every entry in deniedTools is one you want denied. A read-only tool with an unusual name lands in deniedTools as unknown — add it to that connector's allowTools.

4. npm run try — a real review, real model, real cost

This is the only layer that spends budget. It proves the whole path: auth, model, sandbox, evidence collection, connectors, prompt, structured output.

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

With no --candidates it sends a set seeded with known flaws — two duplicates, one assertion the code contradicts, and several obvious gaps. That is the point: you are testing the reviewer, so use input whose correct answer you already know.

Judge it on:

• did it put the duplicate in remove?

• did it put the contradicted assertion in modify, citing the code?

• does every missing entry have a real file:line, not a vague area?

• is the repository unchanged afterwards (git status)?

A PASS on the seeded set means something is wrong, not that your code is clean.

Supply --candidates with your own JSON to rehearse a real workflow:

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

5. End-to-end fixture — opt-in

CODEX_MCP_E2E=1 npm test -- tests/e2e

Builds a fixture repository containing a real coverage gap (idempotency) and a bug report that router middleware already refutes, runs a full qualification against the real Codex CLI, and asserts the fixture is byte-identical afterwards. Takes a few minutes.

Driving it as an MCP server

Once the layers above pass, drive it the way a client will:

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

Then register it in Claude Code and use it on a real ticket.

Development

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

Known limitations

Deferred rather than hidden:

• No stateful continuation. maxPasses defaults to 1 because a second pass has no memory of the first. Multi-pass review needs a request carrying reviewId, previousFindings, authorResponses, and revisedCandidate.

• Read scope is not confined to the project. See read scope. A container or VM with only the project mounted is the only reliable bound today.

• Assembled prompts are large — roughly 4.8k tokens for test-design and 5.4k for bug-review, before evidence. Nearly all of it is the coverage dimensions and discovery checks, which are the substance of the review.

License

MIT