codex-mcp

An MCP (Model Context Protocol) server that wraps the OpenAI Codex SDK, enabling any MCP-compatible client (Claude Code, Cursor, Windsurf, etc.) to run Codex agents.

No API key required — authenticates via ChatGPT OAuth login.

Features

• codex_execute — Run a prompt through the Codex agent (code generation, bug fixes, refactoring, analysis)
• codex_execute_structured — Get structured JSON output with a custom schema
• codex_resume_thread — Resume a previous Codex thread to continue a conversation with full context
• codex_streamed — Stream execution with detailed intermediate events (reasoning, commands, file changes)

Prerequisites

• Bun v1.0+
• OpenAI Codex CLI — must be installed globally

Setup

1. Install Codex CLI

npm install -g @openai/codex

2. Authenticate with ChatGPT

codex login

This opens a browser for ChatGPT OAuth login. Once authenticated, the server uses your session — no API key needed.

3. Install dependencies

bun install

Tip: You can also pass an api_key parameter to any tool if you prefer using an OpenAI API key instead of OAuth.

4. Run the server

bun run start

MCP Client Configuration

Add this to your MCP client config:

Claude Code

claude mcp add codex-mcp -- bun run --cwd /path/to/codex-mcp src/index.ts

Claude Desktop / Cursor / Generic

Add to your MCP settings JSON:

{
  "mcpServers": {
    "codex-mcp": {
      "command": "bun",
      "args": ["run", "--cwd", "/path/to/codex-mcp", "src/index.ts"]
    }
  }
}

Replace /path/to/codex-mcp with the actual path to this repository.

Tools

codex_execute

Run a prompt through the Codex agent.

Parameter	Type	Required	Description
prompt	string	Yes	The task instruction for Codex
model	string	No	Model to use (default: gpt-5.4, e.g., o4-mini)
sandbox_mode	string	No	read-only, workspace-write, or danger-full-access
working_directory	string	No	Working directory path
reasoning_effort	string	No	minimal, low, medium (default), high, xhigh
approval_policy	string	No	never (default), on-request, on-failure, untrusted
web_search_mode	string	No	disabled, cached, live
additional_directories	string[]	No	Extra directories to access
api_key	string	No	OpenAI API key (uses OAuth if omitted)
base_url	string	No	Custom API base URL

codex_execute_structured

Same as codex_execute but returns structured JSON output.

Parameter	Type	Required	Description
prompt	string	Yes	The task instruction
output_schema	object	Yes	JSON Schema for the output format
(other params)			Same as codex_execute

codex_resume_thread

Resume a previous thread to continue the conversation.

Parameter	Type	Required	Description
thread_id	string	Yes	Thread ID to resume
prompt	string	Yes	Follow-up instruction
(other params)			Same as codex_execute

codex_streamed

Run with streaming to capture all intermediate events.

Same parameters as codex_execute. Returns detailed event flow including reasoning steps, command executions, and file changes.

Development

# Run with hot reload
bun run dev

# Type check
bun run check

License

MIT