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.

Why this exists

OpenAI's official Codex plugin for Claude Code drives everything through the Codex CLI — every review or task is a shell subprocess that Claude Code has to spawn, wait on, and poll for output. It reads like it was built without much real Claude Code usage, because that design fights the way the agent actually works:

• Blocking waits. The agent fires a CLI command and then sits idle until the process returns, instead of continuing with other work.

• Late completion signals. Even after Codex has already finished, the "done" signal arrives late, so every step drags and long sessions feel painfully slow.

codex-mcp skips the shell entirely. It exposes Codex to Claude Code as a native MCP server over stdio, so each call is a structured tool invocation — no subprocess spawning, no polling, no delayed completion signals. A ready-made Claude Code plugin (claude-code-codex-plugin/) bundles this server so a background subagent can delegate to Codex cleanly.

Related MCP server: Codex Octopus

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.

Claude Code plugin

The claude-code-codex-plugin/ directory is a self-contained Claude Code plugin that bundles this MCP server plus a delegation subagent.

Layout:

• .mcp.json — runs the committed server bundle (dist/codex-mcp.js) with bun, so there is no bun install / node_modules requirement at runtime; you need only bun, the codex CLI, and a completed codex login.

• agents/codex-runner.md — a background Sonnet subagent. The main thread hands it a task in plain terms; the subagent shapes a single-turn GPT-5.5 Codex prompt, calls the MCP tools, and returns the result. The main model never crafts the prompt itself.

• skills/gpt-5-5-prompting/ — the prompt-crafting guide, loaded only by the subagent (disable-model-invocation: true), so the main model cannot invoke it.

Build the server bundle — a single ~1 MB self-contained JS file with all dependencies inlined. It is committed to the repo (dist/codex-mcp.js), so you only rebuild after changing the server source:

bun run build:plugin   # → claude-code-codex-plugin/dist/codex-mcp.js

The bundle is cross-platform (any OS with bun), small enough to commit, and ships over git as-is — no per-OS build, no Git LFS.

Try it locally:

claude --plugin-dir ./claude-code-codex-plugin

Then ask Claude to hand something to Codex — a code review, a root-cause hunt, a logic/math check, or a bounded fix — and it delegates to the codex-runner subagent in the background.

Install via /plugin

This repo doubles as a plugin marketplace (.claude-plugin/marketplace.json), so you can install it with Claude Code's /plugin command instead of passing --plugin-dir every launch. Because the server bundle is committed to the repo, both a local path and a GitHub clone work with no extra build step.

From a local path:

/plugin marketplace add /path/to/codex-mcp
/plugin install codex-delegate@codex-mcp

From GitHub:

/plugin marketplace add j-token/codex-mcp
/plugin install codex-delegate@codex-mcp

/path/to/codex-mcp is this repo's root — the directory that holds .claude-plugin/marketplace.json. After installing, /plugin (Manage tab) lists it and the subagent appears as @codex-delegate:codex-runner. To ship a new release, rebuild with bun run build:plugin, commit and push, then run /plugin marketplace update codex-mcp.

Tools

codex_execute

Run a prompt through the Codex agent.

codex_execute_structured

Same as codex_execute but returns structured JSON output.

codex_resume_thread

Resume a previous thread to continue the conversation.

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