{"id":14500,"library":"codex-mcp-server","title":"Codex MCP Server","description":"Codex MCP Server (version 1.4.10) is a crucial bridge component designed to integrate OpenAI's Codex CLI with AI agents like Claude Code, providing robust AI-powered code analysis, generation, and review capabilities directly within a developer's editor or IDE. Functioning as an MCP (Model Context Protocol) server wrapper, it translates requests from client applications into commands for the underlying Codex CLI, which then interacts with the OpenAI API. The project maintains an active development pace with frequent patch releases, as evidenced by recent fixes addressing issues like hanging processes and `codex -C` bugs. Its key differentiators include enabling multi-turn conversations with session support, advanced code review features for uncommitted changes or branches, and specialized tools like web search with customizable depth. It requires the globally installed Codex CLI (v0.75.0+) and an authenticated OpenAI API key for operation. The server itself is designed for execution as a command-line process rather than programmatic import into other JavaScript applications.","status":"active","version":"1.4.10","language":"javascript","source_language":"en","source_url":"https://github.com/tuannvm/codex-mcp-server","tags":["javascript","mcp","codex","openai","claude","ai","cli","typescript"],"install":[{"cmd":"npm install codex-mcp-server","lang":"bash","label":"npm"},{"cmd":"yarn add codex-mcp-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add codex-mcp-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a wrapper for the OpenAI Codex CLI and requires the CLI to be installed globally to function. It specifies v0.75.0+.","package":"@openai/codex","optional":false}],"imports":[{"note":"This package is an MCP server designed to be executed as a command-line process or integrated via editor configurations (e.g., `claude mcp add`). It is not intended for direct programmatic import into a Node.js or browser application.","wrong":"import { startServer } from 'codex-mcp-server'","symbol":"Server Execution","correct":"npx -y codex-mcp-server"},{"note":"The primary way to 'import' or enable its functionality within an IDE or AI client is via the client's Model Context Protocol (MCP) configuration, which typically points to the server's command-line invocation.","wrong":"import { createClient } from 'codex-mcp-server'","symbol":"MCP Client Integration","correct":"claude mcp add codex-cli -- npx -y codex-mcp-server"},{"note":"Configuration for MCP clients often involves defining a JSON or TOML structure that specifies how to launch this server, rather than importing specific types or functions. The package ships TypeScript types, but they primarily define internal structures or the MCP protocol, not public API for direct library consumption.","wrong":"import type { McpConfig } from 'codex-mcp-server'","symbol":"MCP Configuration (JSON/TOML)","correct":"{ \"command\": \"npx\", \"args\": [\"-y\", \"codex-mcp-server\"] }"}],"quickstart":{"code":"npm i -g @openai/codex\ncodex login --api-key \"your-openai-api-key\"\n\n# Add to Claude Code or other MCP-compatible editor/client\nclaude mcp add codex-cli -- npx -y codex-mcp-server\n\n# Example usage in your editor/AI client (after server is running)\n// Ask codex to explain this function\n// Use codex to refactor this code for better performance\n// Use review to check my uncommitted changes\n// Use websearch with query \"TypeScript 5.8 new features\"","lang":"bash","description":"Demonstrates installation of prerequisite Codex CLI, authentication, and integration of `codex-mcp-server` as an MCP provider in Claude Code, followed by example prompts for usage."},"warnings":[{"fix":"Explicitly specify the desired model (e.g., `use codex with model 'old-model-id'`) if previous behavior is required, or review your prompts and expected outputs.","message":"The default model used by the `codex` tool was updated to 'codex 5.3' in v1.4.0. This might alter AI behavior or response characteristics if client applications implicitly relied on older defaults.","severity":"breaking","affected_versions":">=1.4.0"},{"fix":"Upgrade to v1.4.10 or newer to prevent processes from hanging due to unclosed stdin.","message":"Prior to v1.4.10, spawned processes could hang, leading to unresponsive sessions. This was addressed by ensuring stdin is closed on child processes.","severity":"gotcha","affected_versions":"<1.4.10"},{"fix":"Upgrade to v1.4.3 or newer to ensure `workingDirectory` functions as expected with the `codex -C` command.","message":"Versions prior to v1.4.3 had a bug where the `codex -C` command's `workingDirectory` was not correctly honored due to how the `cwd` was set for spawned processes.","severity":"gotcha","affected_versions":"<1.4.3"},{"fix":"Client applications should update to handle the absence or conditional availability of `structuredContent`. Check release notes for specific changes regarding `structuredContent` output. Consider enabling `STRUCTURED_CONTENT_ENABLED` if structured output is desired.","message":"The `structuredContent` and `_meta` fields were removed from tool responses in v1.3.2, with `structuredContent` later gated behind `STRUCTURED_CONTENT_ENABLED` in v1.3.4. Relying on these fields in older client integrations might cause issues.","severity":"deprecated","affected_versions":">=1.3.2"},{"fix":"Run `npm i -g @openai/codex` to install the CLI and `codex login --api-key \"your-openai-api-key\"` to authenticate. Ensure `OPENAI_API_KEY` is set as an environment variable or via `codex login` for multi-agent workflows.","message":"The package requires OpenAI's `Codex CLI v0.75.0+` to be installed globally and an OpenAI API key for authentication. Operation will fail without these prerequisites.","severity":"breaking","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `codex login --api-key \"your-openai-api-key\"` in your terminal to authenticate the Codex CLI. Ensure your API key is correct and active.","cause":"The OpenAI Codex CLI is not authenticated or the API key is invalid.","error":"Error: Command failed with exit code 1: codex login"},{"fix":"Install the Codex CLI globally: `npm i -g @openai/codex` or `brew install codex` if applicable.","cause":"The OpenAI Codex CLI (`@openai/codex`) is not installed globally or is not in your system's PATH.","error":"Command not found: codex"},{"fix":"Upgrade `codex-mcp-server` to v1.4.10 or newer to get the fix for hanging processes.","cause":"Older versions of codex-mcp-server could suffer from hanging child processes due to stdin not being closed.","error":"AI response process hung or timed out."},{"fix":"Upgrade `codex-mcp-server` to v1.3.1 or newer, which includes fixes for the `review` command and improved stderr handling.","cause":"Issues with the `review` command and stderr handling were present in earlier versions.","error":"Error: `review` command failed or produced unexpected output."}],"ecosystem":"npm"}