easy-codex-mcp
Provides read-only conversations with OpenAI Codex CLI for code analysis, review, and Q&A in a sandboxed environment.
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., "@easy-codex-mcp Review the code in src/app.js for potential bugs"
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.
easy-codex-mcp
An MCP server that lets any MCP-compatible AI assistant have read-only conversations with OpenAI Codex CLI.
No complex setup β just codex login and you're ready.
Why?
Sometimes your AI assistant needs a second opinion. easy-codex-mcp bridges the gap by letting Claude, Cursor, or any MCP client consult Codex for code analysis, review, and Q&A β all in a non-destructive, read-only sandbox.
π Read-only by design β Codex runs in sandbox mode. It reads your code but never modifies files or runs commands.
π¬ Conversational β Start a thread and continue it later with full context preserved.
π§ Zero config β No API keys to manage in your MCP config. Just log in to Codex CLI once.
Related MCP server: codex-cli-architect-mcp
Quick Start
1. Install Codex CLI
npm install -g @openai/codex
codex login2. Add to your MCP client
Claude Code (recommended):
claude mcp add easy-codex uvx -- --from git+https://github.com/dazebug/easy-codex-mcp easy-codexClaude Desktop β add to your claude_desktop_config.json:
{
"mcpServers": {
"easy-codex": {
"command": "uvx",
"args": ["--from", "git+https://github.com/dazebug/easy-codex-mcp", "easy-codex"]
}
}
}Other MCP clients β use the same config format with uvx as the command.
3. Use it
Your AI assistant now has two new tools:
Tool | Description |
| Start a fresh conversation with Codex |
| Resume a previous conversation using |
Example prompts to your AI assistant:
"Ask Codex to review this file for potential bugs"
"Get Codex's opinion on the architecture of this module"
"Have Codex explain how the authentication flow works"
Tools
start_new_conversation
Start a new read-only conversation with Codex.
Parameters:
prompt(required) β What to ask Codex.working_directory(optional) β Directory for Codex to work in.
Returns: { "thread_id": "...", "response": "..." }
continue_conversation
Resume a previous conversation with full context.
Parameters:
thread_id(required) β Thread ID from a previous conversation.prompt(required) β Follow-up question.working_directory(optional) β Directory for Codex to work in.
Returns: { "thread_id": "...", "response": "..." }
How It Works
Your AI Assistant ββMCPβββΆ easy-codex-mcp ββCLIβββΆ Codex (read-only sandbox)
β β β
β "Review this code" β codex e --json "..." β
βββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β thread_id + response β JSONL output βYour assistant calls the MCP tool with a prompt
easy-codex-mcp spawns
codexCLI in read-only sandbox modeCodex analyzes your code and responds
The response + thread_id are returned to your assistant
Use thread_id to continue the conversation later
Requirements
Python 3.12+
OpenAI Codex CLI (
npm install -g @openai/codex)Codex CLI logged in (
codex login)
Development
git clone https://github.com/dazebug/easy-codex-mcp.git
cd easy-codex-mcp
uv sync
# Run tests
uv run pytest
# Dev mode
uv run mcp dev src/easy_codex/server.pyLicense
MIT
Available Tools
2 toolscontinue_conversationA
Continue an existing Codex conversation.
Resumes a previous conversation using thread_id to maintain context. Same read-only sandbox limitations as start_new_conversation apply.
When to use:
Asking follow-up questions based on previous analysis
Continuing multi-step analysis on the same codebase
Sending additional requests while maintaining conversation context
Args: thread_id: thread_id from a previous conversation. prompt: Follow-up prompt to send to codex. Use @filepath to mention files. working_directory: Directory path for codex to work in (optional).
Returns: Dict with thread_id and response.
Inputs: prompt (required), thread_id (required), working_directory.
start_new_conversationA
Start a new conversation with OpenAI Codex CLI.
Runs codex CLI in read-only sandbox mode and returns a thread_id for continuing the conversation later.
Limitations:
Runs in read-only sandbox β cannot modify files or execute shell commands.
Use only for read-only tasks: code reading, analysis, and Q&A.
When to use:
Analyzing the structure or behavior of a codebase
Code review or root cause analysis of bugs
Generating explanations or documentation drafts for code
Getting refactoring or architecture suggestions
Args: prompt: Prompt to send to codex. Use @filepath to mention files. working_directory: Directory path for codex to work in (optional).
Returns: Dict with thread_id and response.
Inputs: prompt (required), working_directory.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: one starts a new conversation and returns a thread_id, the other continues an existing conversation using that thread_id. There is no overlap or ambiguity between them.
Both tool names follow the same verb_noun pattern with snake_case, using 'start_new_' and 'continue_' as clear action prefixes. This consistency makes the API predictable and easy to navigate.
At only two tools, the count is on the low end but perfectly appropriate for the server's narrow purpose of managing Codex conversations. The tools cover the essential start/continue workflow without unnecessary additions.
The tool surface covers the primary conversation lifecycle (start and continue) with no dead ends. Minor gaps such as the absence of explicit conversation termination or history listing are acceptable given the read-only, session-based scope.
Maintenance
Related MCP Connectors
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
Related MCP Servers
- AlicenseAqualityCmaintenanceBridges OpenAI Codex CLI to any MCP client, allowing headless Codex sessions via tools like codex and codex-reply.244 npm1MIT
- AlicenseAqualityDmaintenanceAn MCP server that provides technical consultation, code review, and code explanation by integrating with OpenAI's Codex CLI, enabling AI-powered coding assistance in a sandboxed, read-only environment.320 npm1MIT
- AlicenseNot gradedqualityDmaintenanceIntegrates OpenAI Codex CLI with Claude Code via MCP, enabling code execution, analysis, fixing, and web search within Claude Code.2,084 npm1ISC
- AlicenseNot gradedqualityDmaintenanceA local, read-only MCP bridge that lets OpenAI Codex ask your authenticated Grok Build CLI for a second opinion without copying API keys into Codex.MIT