codex-research-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@codex-research-mcp research the impact of transformer architecture on NLP tasks"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
researchstarts an independent Codex research thread;research_replycontinues 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-mcpExample 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, defaultcodex;CODEX_RESEARCH_MAX_CONCURRENCY: simultaneous Codex calls, default4;CODEX_RESEARCH_TIMEOUT_SECONDS: per-call timeout, default3600;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 providesource_cwd.
Tests
python3 -m unittest discover -s tests -vAvailable Tools
2 toolsresearchCodex ResearchARead-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 ResearchARead-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
Scored across 2 tools
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.
Both tool names follow the same pattern, using a 'research' base with a clear suffix for the continuation tool. This is consistent and predictable.
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.
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
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
A paid remote MCP for OpenAI Codex context compressor, built to return verdicts, receipts, usage log
No-data MCP handoff for local Claude Code to Codex harness moves. $49 lifetime.
A paid remote MCP for OpenAI Codex memory MCP, built to return verdicts, receipts, usage logs, and a
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceAn experimental guarded MCP bridge for Codex/open-ultrawork workflows, enabling submission of bounded research jobs to ChatGPT Pro asynchronously with source verification and safety guards.MIT
- AlicenseNot gradedqualityDmaintenanceMCP bridge for calling local coding-agent CLIs (Codex, Claude) from another agent, enabling bounded tasks like code review, verification, and bug hunting.MIT
- AlicenseBqualityDmaintenanceMCP bridge for using local Claude CLI as a bounded reviewer and analysis delegate for Codex.5MIT
- AlicenseAqualityBmaintenanceBridges Claude Code and OpenAI Codex through MCP, allowing cross-harness querying, code review, explanation, and implementation delegation.69 npm1MIT