codex-research-mcp

A small local MCP adapter that lets Claude Code delegate bounded research work to Codex plan credits without giving the worker ownership of the final report.

Why it exists

Claude Code only schedules MCP tools concurrently when they advertise readOnlyHint: true. The official generic Codex MCP tools can write to arbitrary workspaces, so they cannot safely make that promise. This adapter exposes a narrower contract:

• research starts an independent Codex research thread;

• research_reply continues a thread created during the current MCP server lifetime;

• real source trees remain read-only;

• every worker receives a private writable scratch directory under /tmp;

• network reads are enabled, while approvals and durable external writes are not;

• both tools advertise the read-only annotation so independent Claude Code tool calls can run concurrently.

The adapter forwards execution to one long-lived official codex mcp-server. Codex still owns model selection, authentication, sessions, and plan-credit use.

Related MCP server: subcodex-mcp

Run from this checkout

./bin/codex-research-mcp

Example Claude Code MCP entry:

{
  "research-worker": {
    "type": "stdio",
    "command": "/Users/zhuhuibin/lab/codex-research-mcp/bin/codex-research-mcp",
    "args": [],
    "env": {
      "CODEX_RESEARCH_MAX_CONCURRENCY": "4"
    }
  }
}

Useful optional environment variables:

• CODEX_RESEARCH_CODEX_BIN: Codex executable, default codex;

• CODEX_RESEARCH_MAX_CONCURRENCY: simultaneous Codex calls, default 4;

• CODEX_RESEARCH_TIMEOUT_SECONDS: per-call timeout, default 3600;

• CODEX_RESEARCH_STATE_DIR: scratch and authorized-thread state, default <system temporary directory>/codex-research-mcp;

• CODEX_RESEARCH_SOURCE_ROOT: default readable source root when a tool call does not provide source_cwd.

Tests

python3 -m unittest discover -s tests -v