Codex MCP Server

1.4.10 · active · verified Sun Apr 19

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.

Common errors

```
Error: Command failed with exit code 1: codex login
```
cause The OpenAI Codex CLI is not authenticated or the API key is invalid.

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.
```
Command not found: codex
```
cause The OpenAI Codex CLI (`@openai/codex`) is not installed globally or is not in your system's PATH.

fix Install the Codex CLI globally: `npm i -g @openai/codex` or `brew install codex` if applicable.
```
AI response process hung or timed out.
```
cause Older versions of codex-mcp-server could suffer from hanging child processes due to stdin not being closed.

fix Upgrade `codex-mcp-server` to v1.4.10 or newer to get the fix for hanging processes.
```
Error: `review` command failed or produced unexpected output.
```
cause Issues with the `review` command and stderr handling were present in earlier versions.

fix Upgrade `codex-mcp-server` to v1.3.1 or newer, which includes fixes for the `review` command and improved stderr handling.

Warnings

breaking 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.
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.
gotcha Prior to v1.4.10, spawned processes could hang, leading to unresponsive sessions. This was addressed by ensuring stdin is closed on child processes.
Fix: Upgrade to v1.4.10 or newer to prevent processes from hanging due to unclosed stdin.
gotcha 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.
Fix: Upgrade to v1.4.3 or newer to ensure `workingDirectory` functions as expected with the `codex -C` command.
deprecated 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.
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.
breaking 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.
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.

Install

npm install codex-mcp-server npm
yarn add codex-mcp-server yarn
pnpm add codex-mcp-server pnpm

Imports

Server Execution
wrong:
```
import { startServer } from 'codex-mcp-server'
```
correct:
```
npx -y codex-mcp-server
```
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.
MCP Client Integration
wrong:
```
import { createClient } from 'codex-mcp-server'
```
correct:
```
claude mcp add codex-cli -- npx -y codex-mcp-server
```
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.
MCP Configuration (JSON/TOML)
wrong:
```
import type { McpConfig } from 'codex-mcp-server'
```
correct:
```
{ "command": "npx", "args": ["-y", "codex-mcp-server"] }
```
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.

Quickstart

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.

npm i -g @openai/codex
codex login --api-key "your-openai-api-key"

# Add to Claude Code or other MCP-compatible editor/client
claude mcp add codex-cli -- npx -y codex-mcp-server

# Example usage in your editor/AI client (after server is running)
// Ask codex to explain this function
// Use codex to refactor this code for better performance
// Use review to check my uncommitted changes
// Use websearch with query "TypeScript 5.8 new features"

view raw JSON →