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.

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:

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

If you already cloned the repository:

./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:

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

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

How it works

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:

[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

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:

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:

[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:

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:

{
  "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.