Let your AI agents talk to Codex.

Setup • Tools • Modes • Models • Tests • Architecture

---

MCP server that wraps the Codex CLI for Claude Code, Gemini CLI, or any MCP client. Session management, sandbox modes, configurable reasoning effort, and structured JSONL output parsing.

• Cross-model conversations — Ask Claude or Gemini to consult Codex for a second opinion, code review, or implementation
• Sandbox modes — read-only, workspace-write, or danger-full-access (matches Codex CLI's -s values)
• Session persistence — Resume multi-turn conversations with the same session id
• Auto-resume on truncated turns — If Codex exits mid-thought, the server resumes once with a continuation nudge before giving up
• No auth in the server — Whatever auth your codex CLI uses (ChatGPT login, OpenAI API key, Bedrock, AWS SDK creds) is what this MCP uses

Setup

Prerequisites

• Codex CLI installed and authenticated (npm install -g @openai/codex)
• Node.js 18+

Install

git clone https://github.com/bobbyrathoree/codex-mcp.git && cd codex-mcp
npm install
npm run build

Add to Claude Code

claude mcp add --scope user codex node /path/to/codex-mcp/dist/index.js

Or add to ~/.claude.json under mcpServers:

{
  "codex": {
    "type": "stdio",
    "command": "node",
    "args": ["/path/to/codex-mcp/dist/index.js"],
    "env": {}
  }
}

Add to Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "codex": {
      "command": "node",
      "args": ["/path/to/codex-mcp/dist/index.js"]
    }
  }
}

Tools

codex_chat

Send a prompt to Codex and get the final answer. Multi-turn via session_id.

message            — The prompt to send
session_id         — Resume a previous conversation (optional)
model              — Model id override (optional; defaults to whatever's in ~/.codex/config.toml)
reasoning_effort   — minimal | low | medium | high | xhigh (optional)
sandbox            — read-only | workspace-write | danger-full-access (default: read-only)
working_dir        — Working root for fresh sessions (resumes inherit original cwd)
skip_git_check     — Allow running outside a git repo (default: true)
timeout_seconds    — Max wait in seconds (default: 600)

Session rules

• First call: omit session_id → fresh session. The response carries the new session_id (Codex's thread id).
• Follow-ups: pass that id back.
• Use only ids returned by your own codex_chat calls — not arbitrary ids from codex_list_sessions.
• On a resumed session the sandbox is inherited from the original session and cannot be changed (Codex exec resume has no -s flag); danger-full-access still applies its bypass.

Example response:

{
  "session_id": "019d5a34-4da0-7ff2-ae4a-0019a6b1fd30",
  "model_used": "gpt-5.5",
  "reasoning_effort": "xhigh",
  "sandbox": "read-only",
  "response": "The project name is codex-mcp, version 1.0.0.",
  "usage": {
    "input_tokens": 16975,
    "cached_input_tokens": 3456,
    "output_tokens": 95,
    "reasoning_output_tokens": 1024
  },
  "response_length": 42
}

If Codex exits before emitting turn.completed even after one auto-resume retry, the response includes incomplete: true and a warning — the response is then a fragment, not a final answer. Resume the session_id to continue.

codex_list_sessions

List recorded Codex sessions from ~/.codex/sessions, newest first. Optional working_dir filter and limit (default 20).

codex_get_session

Get metadata for a specific session id (cwd, created time, CLI version, model provider).

codex_list_models

Returns a curated set of known models plus the configured default and default reasoning effort. (Codex has no native list-models command — models are config-driven.)

Modes

Mode	Codex CLI flag	What Codex can do	Use when
read-only (default)	-s read-only	Read files, run read-only commands — no writes, no network	Research, code review, information gathering
workspace-write	-s workspace-write	Read/write files inside working_dir; still no network by default	Writing code, running builds, file generation
danger-full-access	--dangerously-bypass-approvals-and-sandbox	No sandbox, approvals skipped	Already-isolated environments only

In read-only mode, write attempts are blocked by the sandbox:

touch test.txt: Operation not permitted

Models & Reasoning

Models

The Codex CLI is what picks the model — this MCP just forwards -m when you set the model argument. Omit it to use whatever's in ~/.codex/config.toml. Common ids: gpt-5.5, gpt-5.4, gpt-5-codex. If you're on the Bedrock path the ids are prefixed (e.g. openai.gpt-5.5).

Call codex_list_models to see the curated set this server knows about.

Reasoning Effort

Controls how much thinking the model does before responding. Override per-call with reasoning_effort, or set a default in ~/.codex/config.toml.

Level	Use when
minimal	Trivial single-step asks
low	Quick lookups, simple questions
medium	Standard tasks, moderate complexity
high	Complex code review, multi-file analysis
xhigh	Deep codebase exploration, architectural decisions

Timeout

Default: 600 seconds (10 minutes). High reasoning effort on frontier models can be slow, so don't crank this down without reason. Override with timeout_seconds:

• Long-running tasks: timeout_seconds: 1800 (30 min)
• Quick questions: timeout_seconds: 60 (1 min)

Tests

npm test

17 tests covering JSONL event parsing (including turn.failed/error), exec/resume argument builders, reasoning-effort passthrough, session-meta resolution, and auto-resume on truncated turns.

Architecture

Claude Code / Gemini CLI / MCP Client
        │
        ▼
   codex-mcp (stdio MCP server)
        │
        ▼
   codex exec --json (spawned per request)
        │
        ▼
   Whatever your codex CLI is authed against

• No auth in the server — credentials live with the Codex CLI; this server just forwards args and parses output
• Safe execution — uses spawn() with array args (no shell injection)
• JSONL parsing — clean line-by-line event stream; handles thread.started, item.completed (agent_message), turn.completed, turn.failed, error
• Configurable timeout — per-request, prevents hung processes

How sessions work

First call (no session_id):
  codex exec --json -s read-only -C /project "your prompt"
  → returns thread_id as session_id

Follow-up (with session_id):
  codex exec resume --json <session_id> "your follow-up"
  → resumes with full conversation context

Sessions are stored by the Codex CLI in ~/.codex/sessions/YYYY/MM/DD/rollout-<ISO-ts>-<uuid>.jsonl; the first line is a session_meta record carrying id, cwd, timestamp, CLI version, and model provider.

Environment

MCP servers are spawned by the client without the user's interactive shell exports, so any env vars your codex setup relies on (auth tokens, region pins, etc.) need to be set somewhere the MCP client picks up — ~/.codex/.env, the client's mcpServers[].env block, or your launchd plist, depending on how you launch.

If you use the standalone Codex distribution where ~/.local/bin/codex is a wrapper that exec's into a native binary via CODEX_NATIVE_BINARY, this server pins CODEX_NATIVE_BINARY to ~/.codex/packages/standalone/current/bin/codex on startup when it isn't already set, so it resolves cleanly regardless of how the MCP was launched.

Override env vars:

• CODEX_BINARY — codex executable to spawn (default codex from PATH)
• CODEX_NATIVE_BINARY — the real native binary the standalone wrapper exec's into
• CODEX_HOME — session/config root (default ~/.codex)

License

ISC