Skip to main content
Glama
codex-app-mcp

codex-app-mcp

by abetoots

codex-app-mcp

What this is

codex mcp-server was deprecated in codex-cli 0.149.1 and removed in 0.153.0 (PR #42993). This is a thin stdio MCP server that re-exposes the same codex / codex-reply tool interface the removed server offered, but drives it by talking to codex app-server — the official (if experimental) JSON-RPC successor protocol — instead of shelling out per call.

Related MCP server: opencode-codex-mcp

Requirements

  • Node >= 20

  • the codex CLI on PATH, already authenticated (codex login, or an API key) — auth is not this server's job

  • a codex-cli new enough to have codex app-server (developed and tested against codex-cli 0.154.0)

Install

npm install
npm run build

Register with Claude Code

claude mcp add --scope user codex -- node /home/anon/tmp-create-codex-mcp/dist/index.js

By default the server spawns codex from PATH. Set CODEX_BIN to point at a specific binary if the one you want isn't first on PATH, e.g.:

CODEX_BIN=/path/to/codex claude mcp add --scope user codex -- node /home/anon/tmp-create-codex-mcp/dist/index.js

Tools exposed

Both tools mirror the removed codex mcp-server's 0.151.0 interface, so existing skills/tooling that call mcp__codex__codex / mcp__codex__codex-reply need no changes.

codex — starts a new thread (a persisted codex conversation)

Param

Values

Default

Note

prompt

string

—

required

model

string

Codex config

model for the new thread

effort

string

Codex config

reasoning effort; see note below

cwd

string

server cwd

the thread is bound to this directory's real path

grant

string

—

optional session grant id, checked with the hub's grant checker

approval-policy

untrusted | on-failure | on-request | never

never

on-failure maps to on-request — app-server dropped that value

sandbox

read-only | workspace-write | danger-full-access

read-only

config

—

—

refused when present: a thread gets MCP servers only from the project's files

base-instructions

string

—

optional

developer-instructions

string

—

optional

compact-prompt

string

—

folded into developer-instructions

timeout-seconds

number

900

profile

—

—

rejected outright — app-server has no equivalent field

codex-reply — continues an existing thread

Param

Values

Default

Note

threadId

string

—

required, or use conversationId

conversationId

string

—

deprecated alias for threadId

prompt

string

—

required

cwd

string

bound cwd

optional; refused unless it is the directory the thread was started in

model

string

thread's current

switches the thread from this turn on

effort

string

thread's current

switches the thread from this turn on

timeout-seconds

number

900

Model and effort stick. Codex applies a per-turn model or effort to that turn and every later turn in the thread, so codex-reply without either keeps whatever the thread last used. Valid effort values depend on the model (for gpt-6.1-sol: low, medium, high, xhigh, max, ultra). The server checks the requested effort against the model's advertised list and refuses it, without sending anything, if it isn't there. Codex itself would store an invalid value and fail every later turn on that thread.

Thread bindings

codex asks the grant checker (AI_GRANT_CHECK, default $HOME/ai-cli-sync/bin/grant-check) before it starts a thread, then records the thread's cwd, project, grant, standing-scope hash, approval policy, sandbox and model in CODEX_MCP_STATE_DIR (default ~/.local/state/codex-app-mcp/bindings; directory 0700, files 0600). codex-reply takes all of these from the binding, never from the caller: a thread with no readable binding is refused, the grant is checked again (phase: resume) before the thread is resumed and again once the turn reaches the front of the thread's queue, and a changed standing scope means starting a new thread. A model switched by a reply is written back to the binding, so a restart resumes on it. A checker that cannot run denies.

Result shape (both tools)

content[0].text is the final answer, and structuredContent.content carries the same text. The duplication is deliberate: Claude Code shows the calling model only structuredContent when both are present, so an answer that lives only in content is invisible to it. structuredContent also carries threadId, turnId, status, declinedRequests (approval requests this server auto-declined, since it runs headless), and upstreamErrors (any error notifications app-server sent during the turn). threadId is absent only when thread/start itself fails.

Updating this server

After git pull (or any local fix) + npm run build, restart or reconnect any Claude Code session that already had this server connected — a running Node process doesn't pick up a rebuilt dist/ on its own; it keeps serving whatever was on disk when Claude Code spawned it. In Claude Code, open the /mcp panel, find codex, and choose Reconnect (discards the cached tool list and respawns the process; no full session restart needed). Confirmed live (2026-09-15) as the actual cause of an already-fixed bug appearing to recur across sessions that predated the fix.

To check which version a running server is on, look at its stderr: it logs [codex-app-mcp] starting vX.Y.Z (pid N) on every startup.

Testing

  • npm test runs the full suite (91 tests) against tests/fake-app-server.mjs, a scripted stand-in for codex app-server. Fast, no network, no auth needed — this is what CI/every commit should run.

  • bin/smoke.sh (or CODEX_LIVE=1 npm run smoke) runs a real end-to-end check against your actual codex CLI: starts a thread, gets a reply, continues it same-process, then continues it again from a fresh AppServerClient (simulating a process restart), plus one call through the tools.ts handler layer. Run this after every codex update — codex app-server is an experimental/unstable protocol surface, and this is the drift alarm that catches it before a skill call does.

Fallback note

If codex app-server's protocol changes enough to make this wrapper costly to maintain, 0Pinky0/codex-mcp-sidecar's CODEX_MCP_SIDECAR_COMPAT=1 adapter was evaluated as a fallback (see ~/.claude/docs/decisions/2026-09-14-codex-leg-transport.md).

Architecture

AppServerClient (JSON-RPC framing over the child's stdio, request correlation, notification/server-request dispatch) is wrapped by TurnRunner (thread/turn lifecycle, approval declines, per-thread serialization, timeouts), which tools.ts adapts to the MCP tool contract (zod schemas, kebab-case field mapping, result shaping). src/index.ts wires these together behind a lazy child spawn that respawns automatically if the codex app-server process ever exits. schema/ is regenerated from the installed codex CLI before every test run (pretest), so any protocol drift shows up immediately as test failures rather than at runtime.

Available Tools

2 tools
codexB

Runs a prompt against Codex over a long-lived codex app-server child, starting a new thread. Mirrors the removed codex mcp-server's codex tool (0.151.0 field set); profile is not supported (app-server has no equivalent) and compact-prompt is folded into developer-instructions.

Inputs: prompt (required), cwd, model, config, +7 more.

codex-replyA

Continues an existing Codex thread started by codex (or a previous session) with a follow-up prompt. Mirrors the removed codex mcp-server's codex-reply tool; conversationId is accepted as a deprecated alias for threadId.

Inputs: prompt (required), threadId, conversationId, timeout-seconds.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have clearly distinct roles: codex starts a new thread, while codex-reply continues an existing thread using a threadId. There is no meaningful overlap or ambiguity between them.

    Naming Consistency4/5

    Both names share a consistent codex prefix and the -reply suffix clearly marks the continuation operation. The naming is not a strict verb_noun convention, but the pattern is predictable and understandable.

    Tool Count3/5

    With only two tools, the server feels minimal, but this is arguably appropriate for a narrow conversation-thread workflow. It falls into the borderline range where the count is thin but not unreasonable.

    Completeness4/5

    The server covers the core lifecycle of Codex interactions: starting a new thread and continuing an existing one. There are minor gaps such as no explicit session listing or cancellation, but agents can work around them using the returned thread IDs.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients and external AI supervisors to oversee and steer native Codex sessions through a thin local stdio bridge. It exposes eleven codex_* supervisory tools for tasks such as listing threads, starting turns, observing progress, steering, responding to approvals, interrupting, checkpointing, and rolling over work.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP clients to run non-interactive Codex CLI sessions via codex and codex-reply tools, including resuming conversations by thread ID and passing codex exec flags.
      2
      141 PyPI
      MIT