# Codex Claude Code MCP

A small MCP server for delegating long-running work from Codex to Claude Code without application-level polling.

It intentionally exposes only:

- `claude_code_models`: list models available to the authenticated Claude Code CLI without running a model inference turn.
- `claude_code_run`: start a persisted Claude Code session and block until the turn ends.
- `claude_code_resume`: resume a returned session ID and block until the turn ends.

There is no `poll`, `check`, or `get_status` tool. Model discovery is a short read-only initialization request, not a background task. For background behavior, a Codex parent delegates the blocking run/resume call to a native Codex subagent and waits on Codex's own agent mailbox. See [the Codex subagent workflow](docs/CODEX_SUBAGENT_WORKFLOW.md).

The repository also ships two global Codex skills:

- `claude-code-blocking-direct`: the current agent makes one blocking MCP call and waits.
- `claude-code-blocking-background`: the parent spawns a native Codex subagent to own the blocking call, continues useful work, and later receives the result through Codex's native agent mailbox.

## One-command install

Install the MCP server, validate its build, update `~/.codex/config.toml`, and install both skills globally:

```bash
curl -fsSL https://raw.githubusercontent.com/Happenmass/codex-claude-code-mcp/main/install.sh | bash
```

If you already cloned the repository:

```bash
./install.sh
```

The installer requires Node.js 20+, npm, Git, and an authenticated Claude Code CLI. It installs remote bootstrap checkouts under `~/.codex/tools/codex-claude-code-mcp` by default and skills under `${CODEX_HOME:-$HOME/.codex}/skills`. It creates `config.toml.bak` before replacing an existing `claude-code-blocking` MCP entry.

Restart Codex after installation so it discovers the new MCP server and skills.

Example prompts:

```text
Use $claude-code-blocking-direct to ask Claude Code to review this change and wait for the result.
```

```text
Use $claude-code-blocking-background to have Claude Code review the test strategy while you continue implementing.
```

## How it works

```text
Codex parent
  ├─ continues its own work
  └─ Codex subagent
       └─ one blocking MCP call
            └─ Claude Agent SDK query stream
                 └─ final result / failure / cancellation
```

MCP progress notifications are throttled (20 seconds by default). They describe activity but are not required for completion and do not require a model turn to poll.

## Requirements

- Node.js 20 or newer
- A working Claude Code installation/authentication
- Codex with MCP stdio support

## Claude executable resolution

The bridge prefers the user's current system Claude Code installation so model
routing and authentication match interactive Claude Code. Resolution order:

1. Tool input `pathToClaudeCodeExecutable`
2. Environment variable `CLAUDE_CODE_MCP_PATH`
3. Command named by `CLAUDE_CODE_MCP_COMMAND`
4. `claude`, then `claude-internal`, from `PATH`
5. The Claude Agent SDK bundled binary

`CLAUDE_CODE_MCP_PATH` and `CLAUDE_CODE_MCP_COMMAND` are mutually exclusive.
For a deterministic Codex installation, set:

```toml
[mcp_servers.claude-code-blocking.env]
CLAUDE_CODE_MCP_PATH = "/opt/homebrew/bin/claude"
```

## Model discovery

Call `claude_code_models` before run/resume when the user asks what models are available or when a model identifier needs validation. It returns a stable normalized catalog containing:

- the model value accepted by `claude_code_run` and `claude_code_resume`;
- the resolved model when Claude Code reports one;
- display name and description;
- supported effort levels and adaptive-thinking, fast-mode, or auto-mode capabilities.

The tool starts Claude Code only long enough to read its authenticated initialization catalog, then closes the query. It does not submit a prompt to a model, create a persisted session, or incur an inference turn.

## Manual build

```bash
npm install
npm run typecheck
npm test
npm run build
npm run smoke
```

The smoke test launches the built server through an MCP stdio client and verifies that exactly the model-discovery, run, and resume tools are advertised. It does not spend Claude API credits.

To verify authenticated model discovery through the real MCP stdio path:

```bash
npm run smoke:claude:models
```

This initializes and closes Claude Code without submitting a model prompt. It requires Claude Code authentication but does not create an inference turn. Keep it out of default CI environments that lack a Claude login.

## Manual Codex configuration

Build the project, then add an MCP server entry to `~/.codex/config.toml`:

```toml
[mcp_servers.claude-code-blocking]
command = "node"
args = ["/Users/guhappen/code/codex-claude-code-mcp/dist/index.js"]
tool_timeout_sec = 7200
enabled_tools = ["claude_code_models", "claude_code_run", "claude_code_resume"]

[mcp_servers.claude-code-blocking.env]
CLAUDE_CODE_MCP_PATH = "/absolute/path/to/claude"
```

Restart Codex after changing its MCP configuration. The long client-side tool timeout is intentional: the MCP request itself is the wait primitive.

To install the bundled skills manually:

```bash
cp -R skills/claude-code-blocking-direct "${CODEX_HOME:-$HOME/.codex}/skills/"
cp -R skills/claude-code-blocking-background "${CODEX_HOME:-$HOME/.codex}/skills/"
```

## Tool policy

The default auto-approved tools are only `Read`, `Grep`, and `Glob`.

- `allowedTools`: visible and automatically approved.
- `askTools`: visible, but each use requires MCP elicitation approval.
- `disallowedTools`: always denied and hidden; deny wins over the other lists.

Any tool outside those explicit lists is denied. For an implementation task you might use:

```json
{
  "allowedTools": ["Read", "Grep", "Glob", "Edit", "Write"],
  "askTools": ["Bash"],
  "disallowedTools": ["WebFetch", "WebSearch"]
}
```

If the MCP client does not support elicitation, every `askTools` request is denied rather than silently approved.

## Result and resume

Each call returns compact structured data including `status`, `result`, duration, turn count, cost, and the Claude `sessionId`. Pass that ID to `claude_code_resume` to continue the same context.

MCP request cancellation is forwarded to Claude Code. A server-side runtime limit defaults to two hours and may be set up to eight hours.

## Phase 1 boundary

This design avoids repeated status requests while the Codex task remains active. MCP alone cannot complete a call after its client has disconnected or independently reopen a finished Codex task. Durable cross-turn wake-up requires a Codex-owned thread/automation callback and is outside phase 1.