Codex Persistent MCP

🚀 codex-persistent-mcp

A thin MCP (stdio) server that delegates session persistence to your local codex-cli, enabling MCP calls to create real sessions that users can resume later.

🚀 Quick Start

Recommended: npx Auto-update

Claude Code

claude mcp add-json --scope user codex-persistent \
  '{"command":"npx","args":["-y","codex-persistent-mcp"],"env":{"CODEX_BIN":"/absolute/path/to/codex"}}'

Verify:

claude mcp list
claude mcp get codex-persistent

Codex CLI

codex mcp add codex-persistent --env CODEX_BIN=/absolute/path/to/codex -- npx -y codex-persistent-mcp

Verify:

codex mcp list --json
codex mcp get codex-persistent --json

Antigravity

Antigravity supports adding MCP servers via --add-mcp:

antigravity --add-mcp '{"name":"codex-persistent","command":"npx","args":["-y","codex-persistent-mcp"],"env":{"CODEX_BIN":"/absolute/path/to/codex"}}'

✨ Features

• Other agents can call Codex via MCP and still get a real persisted session.
• Server restarts do not lose context (the context lives in Codex CLI’s session store).
• Users can resume at any time with codex resume <session_id> to continue the same conversation.
• Sessions created via MCP show up in codex resume for the same project (CWD).

📦 Installation

Requirements

• Node.js (recommended: 18+)
• codex-cli (developed against codex-cli 0.77.0)

Install & Build

npm install
npm run build

Install Globally (Optional)

After publishing to npm, you can install it as a global CLI:

npm install -g codex-persistent-mcp

💻 Usage Examples

Run

npm start

Tools

This server exposes 3 primary tools (all return session_id):

• codex_chat
  • input: session_id? (UUID), prompt, cwd?, model?, reasoning_effort?, timeout_ms?
  • output: session_id, reply, usage?
• codex_plan
  • input: session_id?, requirements, plan, constraints?, cwd?, model?, reasoning_effort?, timeout_ms?
  • output: session_id, critique, usage?
• codex_review
  • input: session_id?, change_summary, test_results?, open_questions?, cwd?, model?, reasoning_effort?, timeout_ms?
  • output: session_id, review, usage?

Backward-compatible tool names are still available: codex_guard_plan and codex_guard_final.

🔧 Technical Details

How it Works (Why codex resume Works)

Each tool call spawns a codex subprocess:

• new session:
  • codex exec --skip-git-repo-check --json -C <cwd> "<prompt>"
• resume session:
  • codex exec --skip-git-repo-check --json -C <cwd> resume <session_id> "<prompt>"

The server parses the JSONL event stream produced by --json:

• Reads thread.started.thread_id as the MCP session_id
• Collects item.completed events of type agent_message and returns the final message as reply

Requests for the same session_id are serialized to avoid out-of-order writes.

Environment Variables

• CODEX_BIN: path to the codex executable (default: codex)
• CODEX_PERSISTENT_MCP_ORIGIN: identifier injected into every prompt (default: codex-persistent-mcp)

Working Directory (cwd)

Codex stores session metadata including the workspace CWD, and codex resume filters sessions by CWD by default.

• When starting a new session (no session_id), you must pass cwd (repo root).
• When resuming (with session_id), cwd is optional: the server will reuse or infer it from Codex’s local session store.

“AI vs human” Attribution

Codex CLI does not automatically know that an input came from another AI via MCP. This server always injects a small header into every request so Codex can reliably distinguish:

• Messages with <<<MCP_CONTEXT_BEGIN>>> → from an AI agent via MCP (reply to the agent)
• Messages without it → from the human user (e.g. codex resume)

Per-request Model + Reasoning Overrides

By default, Codex CLI reads your ~/.codex/config.toml (e.g. model and model_reasoning_effort). This MCP server supports per-request overrides:

• model: passed to codex exec -m <model> for that request only
• reasoning_effort: passed as codex exec -c model_reasoning_effort="..." for that request only

If you do not pass these fields, the request follows Codex CLI defaults.

Version Pinning vs Auto-update

npx -y codex-persistent-mcp generally pulls the latest version, which is convenient but less reproducible. To pin a version:

npx -y codex-persistent-mcp@0.1.3

Suggested Workflow (two-agent guardrail)

• Before planning: send “requirements + draft plan” to codex_plan to get gaps/risks/questions/tests.
• Before finishing: send “change summary + test results + open questions” to codex_review for a final review.
• At any time: use codex resume <session_id> to continue the same session manually.

📚 Documentation

Troubleshooting

codex not found

Common when PATH is not inherited (e.g. nvm). Fix by setting:

• CODEX_BIN=/absolute/path/to/codex (use which codex to find it)

Why pass cwd?

Pass your project root so Codex records the correct workspace context and codex resume shows the session in that repo by default.

npm publish requires 2FA (maintainers)

Some npm accounts are required to use two-factor authentication (2FA) or an automation/granular token that can bypass 2FA when publishing.

• Enable 2FA for writes:
  • npm profile enable-2fa auth-and-writes
• Then publish with a one-time password (OTP):
  • npm publish --otp=123456