ask-codex-mcp

Ask Codex MCP

MCP server that connects any AI client to OpenAI Codex CLI

An MCP server for AI-to-AI collaboration via the Codex CLI. Works with Claude Code, Claude Desktop, Cursor, Warp, Copilot, and 40+ other MCP clients. Access GPT-5.5 for code generation, analysis, and review with automatic fallback to GPT-5.4-mini on quota limits.

Part of the Ask LLM monorepo.

Quick Start

Claude Code

claude mcp add codex -- npx -y ask-codex-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "codex": {
      "command": "npx",
      "args": ["-y", "ask-codex-mcp"]
    }
  }
}

Any MCP Client

{
  "command": "npx",
  "args": ["-y", "ask-codex-mcp"]
}

Prerequisites

• Node.js v20.0.0 or higher
• Codex CLI installed and authenticated

Tools

Tool	Purpose
ask-codex	Send prompts to Codex CLI. Defaults to GPT-5.6 Sol at medium effort with automatic Terra fallback; optional reasoningEffort override
ping	Connection test — verify MCP setup without using tokens

Models

Model	Use Case
gpt-5.6-sol	Default — flagship capability
gpt-5.6-terra	Automatic balanced fallback on quota errors

Environment variables

Variable	Default	Purpose
ASK_CODEX_MODEL	gpt-5.6-sol	Override the default model
ASK_CODEX_PREFERRED_MODEL	gpt-5.6-sol	Legacy review-tier escape hatch; only attempted separately when it differs from the default
ASK_CODEX_FALLBACK_MODEL	gpt-5.6-terra	Override the quota-fallback model
ASK_CODEX_REASONING_EFFORT	medium	Default reasoning effort (low, medium, high, xhigh, or max); per-call reasoningEffort wins
ASK_CODEX_LOAD_USER_CONFIG	(unset)	Set to 1 to opt back into loading ~/.codex/config.toml (hooks, MCP servers, preferences) and execpolicy .rules files. By default the wrapper passes --ignore-user-config --ignore-rules so behavior stays deterministic across host machines. Auth credentials in CODEX_HOME always load regardless. See ADR-071.
ASK_CODEX_TIMEOUT_MS	800000	Per-call timeout for the spawned codex process (13.3 min — reasoning models routinely take 5–10 min on substantive prompts; raised in ADR-074)
GMCPT_TIMEOUT_MS	(unset)	Cross-provider timeout override; lower precedence than ASK_CODEX_TIMEOUT_MS
GMCPT_LOG_LEVEL	warn	debug, info, warn, or error

Documentation

Full docs at lykhoyda.github.io/ask-llm

License

MIT