codex-claude-mcp

A local stdio MCP server that lets Codex ask Claude Code for an independent opinion or delegate a task, then follow up on the same Claude conversation. Adapted from cc-codex-mcp by NtTestAlert (MIT).

• claude_ask: start a session in a project directory.

• claude_followup: resume an explicit bridge-owned session.

• Isolated CLAUDE_CONFIG_DIR (default ~/.claude-reviews). Claude login credentials are never copied.

• Per-call subprocesses, cross-process session locks, progress, timeout/cancellation with process-tree cleanup, partial results and large-answer files.

• No enforced read-only sandbox. Claude's permission mode is selected on session creation and preserved on follow-up. Read-only enforcement is on the roadmap.

Setup

Requires Node.js >=20.3 and a separately installed Claude Code CLI. The initial compatibility baseline is Claude Code 2.1.277. Use your existing Claude Code authentication method; the isolated configuration needs its own login.

git clone https://github.com/NtTestAlert/codex-claude-mcp.git
cd codex-claude-mcp
npm install
npm run build
node dist/index.js --doctor

Doctor resolves the executable, validates the isolated home, syncs configuration, and checks claude auth status --json in that home. It makes no model call and reports only authentication status/method, not account details. It prints the login command. node dist/index.js --auth-status checks authentication alone (exit 0 authenticated, 1 unauthenticated, 2 unknown/check failed). Doctor stays usable before login. On Windows, powershell -File scripts/login.ps1 performs that login. On POSIX:

CLAUDE_CONFIG_DIR="$HOME/.claude-reviews" claude auth login

Add to Codex's config.toml, using absolute paths (a real Node executable is recommended on Windows to avoid version-manager shim behavior):

[mcp_servers.claude]
command = "C:/path/to/node.exe"
args = ["C:/path/to/codex-claude-mcp/dist/index.js"]
startup_timeout_sec = 20
tool_timeout_sec = 3700

Restart the Codex session after registration. See AGENTS.snippet.md for optional project instructions.

Related MCP server: claude-consult-mcp

Tools

Both tools accept prompt, optional model, optional effort (low, medium, high, xhigh, max) and timeout_sec (10–3600, default 900). Model/effort support is validated by Claude itself; values are not translated from Codex reasoning levels.

claude_ask also requires cwd and accepts permission_mode: manual (the default), default (legacy alias for manual), acceptEdits, auto, plan, dontAsk, or bypassPermissions. Claude itself enforces model/account availability and organization policy for auto mode. Noninteractive calls cannot display interactive approvals: operations requiring approval may be denied. bypassPermissions explicitly opts out of Claude's permission prompts. It is not enabled automatically.

Optional allowed_tools supplies explicit Claude permission rules at session creation, for example ["Bash(git diff *)", "Bash(git status *)"]. These are preserved on follow-ups and restart. They pre-approve matching actions; they do not restrict tool visibility or enforce read-only access. No rules are granted implicitly. Do not rely on Claude's built-in read-only command checks: the live manual-mode test denied our Git diff command without an explicit allow rule. Organization denies and other Claude policy still apply.

claude_followup requires session_id from an earlier ask. It restores the session's cwd, permission mode and explicit tool rules; optional model/effort overrides persist in bridge metadata. These overrides intentionally change that session's subsequent defaults; pass another override to change them again. A missing cwd is an error, never a fallback to another project. Different sessions can run concurrently; calls on the same session are serialized.

Results contain session_id, answer, duration_sec, warnings, activity, and, when applicable, error and answer_file. Errors are also MCP tool errors. Interrupted calls retain their bridge ID, but resuming is possible only if Claude created its underlying transcript before interruption. Long answers are retained in a temporary file; callers are responsible for removing retained answer files.

Example result (illustrative):

{
  "session_id": "7c280530-f6b8-4cc7-8759-929966932dfa",
  "answer": "The change replaces addition with subtraction.",
  "duration_sec": 8.2,
  "warnings": ["MCP server documentation startup failed"],
  "activity": { "commands": 1, "mcp_tool_calls": [], "subagent_events": 0 }
}

MCP startup failures and authentication-required statuses in Claude's init events are reported in warnings even when stderr is empty. Error payloads that may contain configuration secrets are omitted from these startup warnings. Login advice is attached only to errors recognized as authentication failures.

Timeouts

timeout_sec is the bridge's call budget, including waiting for a session lock. On timeout, cancellation, shutdown, or client stdin EOF the active process tree is terminated. Cleanup can take a few additional seconds. Codex's tool_timeout_sec is a separate outer deadline: 3700 seconds accommodates the bridge's maximum 3600-second run plus cleanup. Progress notifications give visibility; they are not assumed to extend Codex's deadline.

Configuration and isolation

Before every run the bridge refreshes generated settings and MCP configuration. It inherits the source model/effort and eligible user MCP servers, excluding both bridge directions to avoid recursion. It never copies credentials, sessions, hooks or permission settings. Source configuration is read-only. Generated files from doctor and session metadata live under .codex-claude-mcp inside the isolated home. Calls use separate configuration snapshots under <isolated home>/.codex-claude-mcp/runs/, removed after the run, including when a large answer file is retained. MCP configuration is no longer written to the system-wide temporary directory. Re-reading config per call is deliberate for freshness; each subprocess gets its own snapshot to avoid concurrent overwrite.

Remote MCP OAuth connections need their own authorization in the isolated home. For a synced server named documentation, register its generated definition in the isolated profile, then log in from an interactive terminal. Claude's MCP management subcommands do not use the bridge's per-call --mcp-config file:

node dist/index.js --doctor
$env:CLAUDE_CONFIG_DIR = "$HOME\.claude-reviews"
$config = Get-Content "$env:CLAUDE_CONFIG_DIR\.codex-claude-mcp\mcp.json" -Raw | ConvertFrom-Json
$entry = $config.mcpServers.documentation | ConvertTo-Json -Depth 100 -Compress
claude mcp add-json --scope user documentation $entry
claude mcp login documentation

On POSIX (using jq to extract the definition):

export CLAUDE_CONFIG_DIR="$HOME/.claude-reviews"
entry=$(jq -c '.mcpServers.documentation' "$CLAUDE_CONFIG_DIR/.codex-claude-mcp/mcp.json")
claude mcp add-json --scope user documentation "$entry"
claude mcp login documentation

Use your configured bridge home if it differs from the default. Doctor generates the referenced file without modifying the source configuration. Skip add-json if this server is already registered in the isolated profile. For headless terminals, claude mcp login --no-browser documentation prints the authorization URL instead of launching a browser.

Claude still loads applicable project instructions/settings according to its own rules. Configuration isolation is not filesystem sandboxing. The bridge passes an explicit MCP configuration with --strict-mcp-config instead of automatically loading project MCP servers. Parent environment credentials remain available to Claude; an API key can select API billing rather than subscription authentication.

Development

npm test

Tests use temporary directories and fake Claude processes, not paid model calls. The explicit npm run test:live command makes two real Claude calls using the isolated login: a review of a disposable Git diff and a follow-up after fixing it. It uses manual mode with the explicit Bash(git diff *) allowance and no permission bypass. Add --without-allow-rules to reproduce the baseline permission check. Use npm run test:live -- --permission-mode=plan to check plan mode separately. The default live-test model is sonnet; CLAUDE_BRIDGE_LIVE_MODEL overrides it. Live transcripts stay in the isolated profile; the disposable project is removed. Windows is the primary target. POSIX process-group cleanup is implemented but requires validation on macOS/Linux. As in the original bridge, a parent crash before cleanup can leave a grandchild behind on Windows (no Job Object).

Roadmap: enforced read-only profile, broader platform validation, configuration watching (currently refreshed per call), and optional asynchronous job tools.

Verification record

Checked against installed Claude Code 2.1.277: print mode, stream-json output, explicit session IDs and resume, model/effort flags, manual/auto permission modes, allowedTools, strict MCP config, and auth status --json. Automated tests exercise the real MCP transport against fake Claude subprocesses, including restart, EOF cancellation, permission-rule persistence, startup diagnostics and auth checks.

Live checks on Windows, 2026-10-21, Claude Code 2.1.277, sonnet, low effort:

These tests used a disposable staged Git fixture, no permission bypass, and an empty source MCP config to keep the check focused on local Git access. They do not certify every synced MCP server or a production repository's policies. Automated suite: 52 passed, 1 platform-specific skip.