Codex MCP

A lightweight Model Context Protocol (MCP) server that exposes the local Codex CLI (codex) to MCP-compatible coding agents.

The project intentionally keeps the architecture small: MCP tools validate inputs, a thin CLI adapter executes codex exec (and friends), and codex_raw provides an escape hatch for CLI options that are added in future Codex releases.

Features

• Run Codex as a local coding agent through MCP (codex exec).

• Run non-interactive code reviews (codex exec review).

• Resume or fork previous sessions (codex exec resume / codex exec fork).

• Control common CLI options such as model, sandbox policy, approval behavior, extra directories, images, and output handling.

• Inspect version, login status, and diagnostics (codex doctor).

• Pass arbitrary CLI arguments through codex_raw for forward compatibility.

• No shell execution: arguments are passed directly to the codex process (shell: false).

• Optional server-wide model override via an environment variable (see below).

Related MCP server: codex-mcp-server

Requirements

• Node.js 18+

• Codex CLI installed and authenticated (codex login)

• codex available on PATH

• An MCP-compatible client

If codex is not on PATH, set CODEX_MCP_CMD to the executable path.

CODEX_MCP_CMD=/custom/path/codex

Windows PowerShell:

$env:CODEX_MCP_CMD = "C:\path\to\codex.exe"

Forcing a specific model

Every tool that runs the agent (codex_run, codex_review, codex_resume, codex_fork, and codex_raw when its first argument is exec) accepts a model input. If you set the CODEX_MCP_MODEL environment variable on the MCP server process, it overrides the model for every such call, regardless of what the caller (or a raw argument list) requests. This is useful when you want to pin the server to a single model — for cost control, quota limits, or consistency — no matter what any individual tool call asks for.

CODEX_MCP_MODEL=your-model-id

The override is applied last, after stripping any -m/--model flag or -c model=... config override already present in the constructed arguments, so it always wins. It is never applied to subcommands that don't accept a model (--version, login status, help, doctor, ...), so those keep working normally even when the override is set.

Quick Start

The recommended setup is through npm. You do not need to clone this repository or install the MCP server manually.

Claude Code

claude mcp add --scope user codex -- npx -y codex-mcp

Verify the server:

claude mcp list

If codex is not on PATH, or you want to pin the model:

claude mcp add --scope user \
  --env CODEX_MCP_CMD=/custom/path/codex \
  --env CODEX_MCP_MODEL=your-model-id \
  codex -- npx -y codex-mcp

Gemini CLI

gemini mcp add --scope user codex npx -y codex-mcp

Verify:

gemini mcp list

Cursor

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

Windsurf

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

Cline / Roo Code / Other MCP Clients

{
  "command": "npx",
  "args": ["-y", "codex-mcp"]
}

If the client supports environment variables, CODEX_MCP_CMD and CODEX_MCP_MODEL can be set there as well.

Local Development

git clone https://github.com/alvarosw/codex-mcp.git
cd codex-mcp
npm install
npm start

No build step is required.

Testing

npm test runs a static syntax check only — it makes no network calls and costs nothing.

npm run test:live drives the real MCP server end to end over stdio against a real, authenticated Codex CLI (in a throwaway temp git repo it creates and cleans up). It exercises every tool, including verifying that CODEX_MCP_MODEL (if set) wins over a deliberately wrong model passed in a tool call or smuggled into codex_raw arguments. This makes real model calls and is not run automatically — you need codex login completed first, and it will consume real quota/tokens against whichever model resolves for the call:

CODEX_MCP_MODEL=your-model-id npm run test:live

CODEX_MCP_MODEL is optional for this script; without it, the override-specific assertions are skipped and the rest of the suite still runs against your account's default configured model.

Tools

codex_run

Run Codex as an agent non-interactively (codex exec) with common CLI controls: prompt, model, sandbox policy, approval routing, extra directories, images, working directory, ephemeral/persisted sessions, and raw passthrough args.

Example:

{
  "prompt": "Review the authentication implementation and identify security issues.",
  "cwd": "/workspace/project",
  "sandbox": "workspace-write",
  "addDirs": ["/workspace/shared"]
}

codex_review

Runs codex exec review non-interactively against the current repository. Supports uncommitted, base, commit, and title, plus a custom review prompt.

codex_resume

Resumes a previous session (codex exec resume) by sessionId, or the most recent one if omitted, optionally sending a new prompt.

codex_fork

Forks a previous session (codex exec fork) by sessionId into a new session, optionally sending a prompt.

codex_version

Returns the installed Codex CLI version.

codex_login_status

Runs codex login status to check authentication state.

codex_doctor

Runs codex doctor --json for install, auth, config, and connectivity diagnostics.

codex_help

Shows CLI help. A command can be provided for command-specific help.

codex_raw

Runs codex with an arbitrary argument array. This is the compatibility escape hatch for flags or commands not covered by the convenience tools. The model override, if set, still applies when the first argument is exec.

Example:

{
  "args": ["mcp", "list"]
}

Architecture

src/
├── index.js   # MCP server and tool registration
├── tools.js   # Tool behavior and response formatting (JSONL event parsing)
└── codex.js   # Thin process adapter for the codex CLI + model-override enforcement

Dependency direction:

MCP transport
    ↓
tool handlers
    ↓
codex CLI adapter
    ↓
local codex executable

There is intentionally no service container, repository layer, or framework abstraction. The project has one external process boundary and keeps that boundary explicit.

Tools that invoke codex exec* request --json internally so output can be parsed reliably; each tool's text response is the agent's final message(s), with the full parsed event stream, command executions, token usage, and thread id available in structuredContent for programmatic consumers.

Security Notes

codex_raw can execute arbitrary Codex CLI arguments with the permissions of the user running the MCP server. The server itself does not invoke a shell, so tool arguments are not shell-interpreted, but codex still has whatever permissions its sandbox and approval settings grant it.

dangerouslyBypassApprovalsAndSandbox skips all confirmation prompts and sandboxing. Only use it when you explicitly trust the task and an already-isolated workspace.

Environment variables passed through the env field are inherited by the codex process. Avoid sending secrets through MCP tool arguments unless necessary.

License

MIT