Codex MCP Server

An MCP server connecting Claude, Cursor, and other AI assistants to OpenAI Codex CLI · npm package @trishchuk/codex-mcp-tool · How I use it as an outside advisor to Claude Code →

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+)
• Local OSS Models — run with Ollama or LM Studio via localProvider
• Web Search — research capabilities with search: true
• Sandbox Mode — safe automation with explicit sandbox and approval policies
• 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.6-sol 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"'

// Local OSS model (Ollama)
'ask codex localProvider:"ollama" model:"qwen3:8b" prompt:"explain @src/"'

Tools

Models

By default the model parameter is omitted and Codex CLI applies the default model from your ~/.codex/config.toml (for example model = "gpt-5.6-sol"). Pass model only when you need to override the configured default for a single call. Reasoning depth is calibrated per tool:

• ask-codex — uses the Codex CLI default reasoning (medium). Increase it only when the task needs more planning or checking.
• brainstorm, do-act, review-changes — default reasoningEffort: "high" (creative ideation, act-check-fix loops, and code review benefit from deeper reasoning).

GPT-5.6 Sol and Terra can expose max and ultra reasoning. ultra may delegate work to subagents; most tasks should remain on medium or high.

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)

Local OSS Models (v1.6.0+)

Run with local Ollama or LM Studio instead of OpenAI:

// Ollama
{ "prompt": "analyze @src/", "localProvider": "ollama", "model": "qwen3:8b" }

// LM Studio
{ "prompt": "analyze @src/", "localProvider": "lmstudio", "model": "my-model" }

// Auto-select provider
{ "prompt": "analyze @src/", "oss": true }

Requirements: Ollama running locally with a model that supports tool calling (e.g. qwen3:8b).

Advanced Options

CLI Compatibility

Validated against Codex CLI 0.144.3. The server keeps older feature guards, but current releases are recommended. Notable current behavior:

• --full-auto and approval policy on-failure have been removed by Codex CLI.
• MCP sandbox: true / fullAuto: true remain compatibility aliases for --sandbox workspace-write --ask-for-approval never; they do not bypass the sandbox.
• Native --search is used without the deprecated web_search_request feature.
• Current exec flags include --strict-config, --ephemeral, --ignore-user-config, and --ignore-rules.

Troubleshooting

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

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

Further Reading

• @trishchuk/codex-mcp-tool on npm
• Source on GitHub
• OpenAI Codex CLI
• Model Context Protocol