Skip to main content
Glama

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: peer-cli-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

Available Tools

2 tools
researchCodex ResearchA
Read-only

Delegate one read-only evidence assignment to Codex for discovery, retrieval, extraction, organization, comparison, calculation, or verification. The real source tree stays read-only; downloads, scripts, and intermediate files are confined to a private temporary scratch directory. Independent calls may run concurrently.

Inputs: prompt (required), source_cwd. Returns: content, threadId

research_replyContinue Codex ResearchA
Read-only

Continue a research thread previously created during the current MCP server lifetime. The original scratch isolation and source boundary remain in force.

Inputs: prompt (required), threadId (required). Returns: content, threadId

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 2 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: research initiates a new read-only evidence assignment, while research_reply continues an existing thread. There is no overlap or ambiguity between them.

    Naming Consistency5/5

    Both tool names follow the same pattern, using a 'research' base with a clear suffix for the continuation tool. This is consistent and predictable.

    Tool Count3/5

    With only two tools, the server feels thin for a research-focused MCP, though the tools are broad in capability. This falls into the borderline range for tool count.

    Completeness5/5

    The two tools cover the complete lifecycle of a research thread: initiating a new assignment and continuing an existing one. The read-only and scratch-isolated boundaries are well-defined, and no obvious operations are missing for the stated purpose.

    Related MCP Connectors

    Related MCP Servers