# codex-mcp

An MCP (Model Context Protocol) server that wraps the [OpenAI Codex SDK](https://github.com/openai/codex), 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.

## 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](https://bun.sh/) v1.0+
- [OpenAI Codex CLI](https://github.com/openai/codex) — **must be installed globally**

## Setup

### 1. Install Codex CLI

```bash
npm install -g @openai/codex
```

### 2. Authenticate with ChatGPT

```bash
codex login
```

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

### 3. Install dependencies

```bash
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

```bash
bun run start
```

## MCP Client Configuration

Add this to your MCP client config:

### Claude Code

```bash
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:

```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/`](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:

```bash
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:**

```bash
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.

| 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` (default: `live` — web search is on unless you pass `disabled`) |
| `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

```bash
# Run with hot reload
bun run dev

# Type check
bun run check
```

## License

MIT