Codex MCP Async
Enable Claude Code to call Codex (GPT-5) asynchronously, filtering out thinking processes to save 95% context tokens.
Installation
npx codex-mcp-asyncAsk AI about Codex MCP Async
Powered by Claude Β· Grounded in docs
I know everything about Codex MCP Async. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Codex MCP Async Server
Asynchronous MCP wrapper for OpenAI Codex CLI with 95% context savings
Enable Claude Code to call Codex (GPT-5) asynchronously, filtering out thinking processes to save 95% context tokens.
Features
- β Async execution - Start Codex tasks in background, continue working
- β Context-efficient - Filters thinking/exec logs, returns only core results
- β Full control - Access all Codex models and reasoning efforts
- β Zero config - Works out of the box with Claude Code
Quick Start
π Install with UVX
Zero configuration - just run:
uvx codex-mcp-async
Configure Claude Code
Add to your ~/.claude/settings.json:
{
"mcpServers": {
"codex-mcp": {
"command": "uvx",
"args": ["codex-mcp-async"],
"env": {}
}
}
}
Or use the provided config: Copy
mcp-config.jsonto your Claude settings directory
Restart Claude Code
Reload or restart Claude Code to load the MCP server.
Usage Examples
π Async Execution (Game Changer!)
Start a long Codex task and continue working immediately:
You:
Please analyze this entire codebase and generate comprehensive documentation
Claude: I'll analyze your entire codebase and generate comprehensive documentation. This is a large task, so I'll start it asynchronously...
β Task Started (Task ID: abc12345) You can continue working on other things while it runs in the background!
You: (Continue working immediately)
While the documentation is being generated, help me fix this bug
Claude: Sure! Let me help you fix that bug...
You: (A few minutes later)
Can you check if the documentation task is finished?
Claude: β Documentation Complete!
[View Generated Documentation]
- API reference
- Code examples
- Architecture overview
- Setup instructions
β‘ Parallel Execution
Run multiple Codex tasks simultaneously:
You:
I need to do three things at once:
- Generate unit tests for utils.py
- Refactor database.py to use async/await
- Add type hints to all functions in api.py
Claude: I'll start all three tasks in parallel!
π Task 1 Started (Task ID: task1) - Generating unit tests π Task 2 Started (Task ID: task2) - Refactoring database code π Task 3 Started (Task ID: task3) - Adding type hints
All tasks are running in parallel...
You: (Later)
Are all three tasks finished?
Claude: β All Complete!
- β Task 1: Unit tests for utils.py generated
- β Task 2: database.py refactored to async mode
- β Task 3: Type hints added to api.py functions
π― Quick Sync Tasks
For simple immediate tasks:
You:
Write a Python function to validate email addresses
Claude:
import re
def validate_email(email):
pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
return re.match(pattern, email) is not None
# Usage examples
print(validate_email("user@example.com")) # True
print(validate_email("invalid-email")) # False
β Task Complete!
π§ Model Selection
You:
Analyze this research paper using GPT-5 with high reasoning
Claude:
# Uses analysis model instead of coding model
mcp__codex_mcp__codex_execute(
prompt="Analyze this research paper on machine learning",
args=["--full-auto", "-m", "gpt-5", "--config", "model_reasoning_effort=high"]
)
Why Async + Context Filtering?
Problem 1: Codex blocks Claude Code while running. Problem 2: Codex outputs 3000+ tokens of thinking logs for every task.
Solution: This MCP server runs Codex asynchronously and filters out 95% of the noise.
Benefits:
- π Start a task and continue working immediately
- β‘ Run multiple tasks in parallel
- πΎ 95% context savings (3000 tokens β 150 tokens)
- π― Clean, focused results only
- π§Ή Automatic process cleanup
Advanced Usage
Model Selection
gpt-5-codex (default) - Best for coding, debugging, implementation
gpt-5 - Best for analysis, planning, research
Reasoning Levels
minimal/low- Quick tasksmedium- Standard work (default)high- Complex problems
Example Configurations
# Quick coding task
args=["--full-auto", "--config", "model_reasoning_effort=low"]
# Complex analysis
args=["--full-auto", "-m", "gpt-5", "--config", "model_reasoning_effort=high"]
# Web search + analysis
args=["--full-auto", "--search", "-m", "gpt-5"]
Architecture & Performance
Claude Code (you)
β calls MCP tool
codex-mcp-async (runs Codex in background)
β filters thinking logs (95% savings!)
Codex CLI (GPT-5)
β returns clean result
Claude Code (receives focused output)
Context Savings:
- Before: 3600 tokens (thinking + logs + result)
- After: 180 tokens (clean result only)
- 95% reduction!
Troubleshooting
Server not showing up?
- Check:
uvx codex-mcp-asyncruns without errors - Restart Claude Code after config change
Task stuck in "running"?
- Large tasks take time to complete
- Check debug logs:
/tmp/codex_mcp_debug.log
Context too large?
- Enable filtering: Always use async mode for long tasks
- Split large tasks into smaller chunks
Requirements
- Python 3.8+
- Codex CLI installed and authenticated
- Claude Code
- uvx (for easy installation)
License
MIT License - see LICENSE
Questions? Open an issue on GitHub.
Made with β€οΈ for the Claude Code + Codex community
