Skip to main content
Glama

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

Related MCP server: 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.json to 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:

  1. Generate unit tests for utils.py

  2. Refactor database.py to use async/await

  3. 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 tasks

  • medium - 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-async runs 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

License

MIT License - see LICENSE


Questions? Open an issue on GitHub.

Made with โค๏ธ for the Claude Code + Codex community

Available Tools

3 tools
codex_check_resultA

Check the status of an async Codex task. Returns running/completed status and the result if available.

Inputs: task_id (required).

codex_executeA

Execute OpenAI Codex (GPT-5) synchronously with full control over subcommand and arguments. Returns only the core result, filtering out thinking process to save context. Common usage: subcommand="exec", prompt="your task", args=["--full-auto"]

Inputs: args, prompt, timeout, subcommand.

codex_execute_asyncA

Start a Codex task in the background and return immediately with a task_id. Use codex_check_result to retrieve the result later. This allows you to continue working while Codex runs.

Inputs: args, prompt, subcommand.

Tool Schema Changelog

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

Loading tool schema changelogโ€ฆ

    TDQS

    A3.8/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool serves a distinct purpose: synchronous execution, async execution, and result checking. No overlap exists between these operations.

    Naming Consistency4/5

    All tools start with 'codex_', but there is a slight inconsistency: 'codex_execute' lacks a 'sync' modifier while its async counterpart has it, and 'codex_check_result' uses a noun phrase. Still, the pattern is mostly predictable.

    Tool Count4/5

    With only 3 tools, the server is minimal but appropriately scoped for its purpose of providing both sync and async code execution with result retrieval.

    Completeness3/5

    The core execution and result checking are covered, but missing features like cancelling async tasks or listing pending tasks create minor gaps in the lifecycle.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers