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
Metadata
Release files for iflow-mcp_jeanchristophe13v_codex-mcp-async 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_jeanchristophe13v_codex_mcp_async-0.2.1.tar.gz | 12.3 kB | Without provenance | Details for iflow_mcp_jeanchristophe13v_codex_mcp_async-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_jeanchristophe13v_codex_mcp_async-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_jeanchristophe13v_codex_mcp_async-0.2.1-py3-none-any.whl |
Total release size: 25.3 kB
Release files / iflow_mcp_jeanchristophe13v_codex_mcp_async-0.2.1.tar.gz
| Download URL | iflow_mcp_jeanchristophe13v_codex_mcp_async-0.2.1.tar.gz |
|---|---|
| Size | 12.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
29a996218115ba8b7b4f3155033a7560f88cb5b7c313909c61d3678dbdef60b1
|
|
BLAKE2b-256 checksum How to use checksums |
748a731db018948184fe5f8d00ea34c7e437462d0622f7e8b46649d9b3aecc2d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.28 {"installer":{"name":"uv","version":"0.9.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_jeanchristophe13v_codex_mcp_async-0.2.1-py3-none-any.whl
| Download URL | iflow_mcp_jeanchristophe13v_codex_mcp_async-0.2.1-py3-none-any.whl |
|---|---|
| Size | 13.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
caea28f3d6a2240ae6f0111f699f1726294055770880d4a592f6e83eb8eb7a8f
|
|
BLAKE2b-256 checksum How to use checksums |
85bbd803d9452e4a9653f7ddbae83de651d3f02ceb9dcdcd420ae7d7bd84c68e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.28 {"installer":{"name":"uv","version":"0.9.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_jeanchristophe13v_codex-mcp-async 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.