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.

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.

• 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)

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

npm install -g @openai/codex

codex login

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

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.

bun run start

Add this to your MCP client config:

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

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.

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.

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.

Run a prompt through the Codex agent.

Same as codex_execute but returns structured JSON output.

Resume a previous thread to continue the conversation.

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.

# Run with hot reload
bun run dev

# Type check
bun run check

MIT