Registry / llm-agents / codex-mcp-server

codex-mcp-server

library1.2.2jsnpmunverified

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.

llm-agents ai-ml devops

npm install codex-mcp-server

github ↗package ↗

INSTALL

IMPORT

SIG · CODEX-MCP-SERVER

codex-mcp-server

llm-agentsjavascriptv1.2.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Server Execution

✓ npx -y codex-mcp-server

✗ import { startServer } from '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

✓ claude mcp add codex-cli -- npx -y codex-mcp-server

✗ import { createClient } from '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)

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

✗ import type { McpConfig } from '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.

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"

codex-mcp-server --version

Debug

Known issues

breakingThe 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.

affects: >=1.4.0

gotchaPrior 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.

affects: <1.4.10

gotchaVersions 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.

affects: <1.4.3

deprecatedThe `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.

affects: >=1.3.2

breakingThe 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.

affects: all

Errors

Common errors & fixes

Error: Command failed with exit code 1: codex login

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

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.

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.

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.

Upgrade

Version history

1.2.2latest on npm

Audit

Dependencies

@openai/codexrequiredThis package is a wrapper for the OpenAI Codex CLI and requires the CLI to be installed globally to function. It specifies v0.75.0+.

Agent activity

31 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/tuannvm/codex-mcp-server ↗

packagehttps://www.npmjs.com/package/codex-mcp-server ↗