Codex MCP Tool

MCP server connecting Claude/Cursor to Codex CLI. Enables code analysis via @ file references, multi-turn conversations, sandboxed edits, and structured change mode.

Features

• File Analysis — Reference files with @src/, @package.json syntax
• Multi-Turn Sessions — Conversation continuity with workspace isolation
• Native Resume — Uses codex resume for context preservation (CLI v0.36.0+)
• Web Search — Research capabilities with search: true
• Sandbox Mode — Safe code execution with --full-auto
• Change Mode — Structured OLD/NEW patch output for refactoring
• Brainstorming — SCAMPER, design-thinking, lateral thinking frameworks
• Health Diagnostics — CLI version, features, and session monitoring
• Cross-Platform — Windows, macOS, Linux fully supported

Quick Start

claude mcp add codex-cli -- npx -y @trishchuk/codex-mcp-tool

Prerequisites: Node.js 18+, Codex CLI installed and authenticated.

Configuration

{
  "mcpServers": {
    "codex-cli": {
      "command": "npx",
      "args": ["-y", "@trishchuk/codex-mcp-tool"]
    }
  }
}

Config locations: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json | Windows: %APPDATA%\Claude\claude_desktop_config.json

Usage Examples

// File analysis
'explain the architecture of @src/';
'analyze @package.json and list dependencies';

// With specific model
'use codex with model gpt-5.2-codex to analyze @algorithm.py';

// Multi-turn conversations (v1.4.0+)
'ask codex sessionId:"my-project" prompt:"explain @src/"';
'ask codex sessionId:"my-project" prompt:"now add error handling"';

// Brainstorming
'brainstorm ways to optimize CI/CD using SCAMPER method';

// Sandbox mode
'use codex sandbox:true to create and run a Python script';

// Web search
'ask codex search:true prompt:"latest TypeScript 5.7 features"';

Tools

| Tool | Description | | --------------- | ------------------------------------------------------ | | ask-codex | Execute Codex CLI with file analysis, models, sessions | | brainstorm | Generate ideas with SCAMPER, design-thinking, etc. | | list-sessions | View/delete/clear conversation sessions | | health | Diagnose CLI installation, version, features | | ping / help | Test connection, show CLI help |

Models

Default: gpt-5.2-codex with fallback → gpt-5.1-codex-max → gpt-5.2

| Model | Use Case | | -------------------- | ---------------------------------------- | | gpt-5.2-codex | Latest frontier agentic coding (default) | | gpt-5.1-codex-max | Deep and fast reasoning | | gpt-5.1-codex-mini | Cost-efficient quick tasks | | gpt-5.2 | Broad knowledge, reasoning and coding |

Key Features

Session Management (v1.4.0+)

Multi-turn conversations with workspace isolation:

{ "prompt": "analyze code", "sessionId": "my-session" }
{ "prompt": "continue from here", "sessionId": "my-session" }
{ "prompt": "start fresh", "sessionId": "my-session", "resetSession": true }

Environment:

• CODEX_SESSION_TTL_MS - Session TTL (default: 24h)
• CODEX_MAX_SESSIONS - Max sessions (default: 50)

Advanced Options

| Parameter | Description | | ---------------------- | --------------------------------------- | | model | Model selection | | sessionId | Enable conversation continuity | | sandbox | Enable --full-auto mode | | search | Enable web search | | changeMode | Structured OLD/NEW edits | | addDirs | Additional writable directories | | toolOutputTokenLimit | Cap response verbosity (100-10,000) | | reasoningEffort | Reasoning depth: low, medium, high, max |

CLI Compatibility

| Version | Features | | -------- | -------------------------------- | | v0.60.0+ | GPT-5.2 model family | | v0.59.0+ | --add-dir, token limits | | v0.52.0+ | Native --search flag | | v0.36.0+ | Native codex resume (sessions) |

Troubleshooting

codex --version    # Check CLI version
codex login        # Authenticate

Use health tool for diagnostics: 'use health verbose:true'

Migration

v1.3.x → v1.4.0: New sessionId parameter, list-sessions/health tools, structured error handling. No breaking changes.

License

MIT License. Not affiliated with OpenAI.

Documentation | Issues | Inspired by jamubc/gemini-mcp-tool