RELATED 01
opencode-mcp
Hands coding tasks from an MCP client to a running OpenCode server and tracks them to completion
161GitHub stars
25k/wknpm downloads
68popularity score
Codex MCP Server
Hands coding tasks, code reviews and web searches from an MCP client to the OpenAI Codex CLI
By Tommy Nguyen (individual) TypeScript Local · stdio AI and MLDeveloper tools
62 popularity score ★ 648 ↓ 1.3k/wk
Connect your client
Local (npm)
Add in one click
Opens the app, which asks before it adds the server.
Or add it by command or config
FirstTerminal
npm i -g @openai/codex
codex login --api-key "<OPENAI_API_KEY>"Claude CodeTerminal
claude mcp add codex -- npx -y codex-mcp-serverClaude Desktopclaude_desktop_config.json
{
"mcpServers": {
"codex": {
"command": "npx",
"args": [
"-y",
"codex-mcp-server"
]
}
}
}Cursor~/.cursor/mcp.json
{
"mcpServers": {
"codex": {
"command": "npx",
"args": [
"-y",
"codex-mcp-server"
]
}
}
}VS Code.vscode/mcp.json
{
"servers": {
"codex": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"codex-mcp-server"
]
}
}
}Codex~/.codex/config.toml
[mcp_servers.codex]
command = "npx"
args = ["-y", "codex-mcp-server"]Gemini CLITerminal
gemini mcp add --scope user codex npx -- -y codex-mcp-serverSettings 4
CODEX_DEFAULT_MODEL |
Optional: Model used when a call gives none; defaults to gpt-5.3-codex at v1.4.10. |
|---|---|
CODEX_MCP_CALLBACK_URI |
Optional: Static MCP callback URI passed to Codex; a callbackUri tool argument overrides it. |
STRUCTURED_CONTENT_ENABLED |
Optional: Set to 1/true/yes/on to return structuredContent with threadId and model metadata; off by default. |
CODEX_HOME |
Optional: Custom directory for the Codex CLI's own configuration. |
What it does
Codex MCP Server is a small stdio bridge that turns the OpenAI Codex CLI into tools an MCP client such as Claude Code can call. Each tool call starts the locally installed `codex` program as a child process (`codex exec`, `codex review`, `codex --search exec` or `codex --help`) and passes its output back, so a second coding agent can be asked for an opinion, a refactor or a review without leaving the first one.
The `codex` tool takes a prompt plus optional model, reasoning effort, sandbox policy, full-auto mode and working directory. Passing a `sessionId` keeps a conversation going: the server records the Codex conversation id and resumes it with `codex exec resume`, falling back to the last two turns as context. Sessions live in the server's memory, expire after 24 hours of inactivity and are capped at 100. The `review` tool reviews uncommitted changes, a branch diff against a base, or a single commit; `websearch` runs Codex with its web search turned on and returns 10 results by default, 1 to 50 with `numResults`.
One thing the README does not say: at version 1.4.10 the default model in the code is `gpt-5.3-codex` (the API reference still says `gpt-5.2-codex`), and it can be changed for all calls with the `CODEX_DEFAULT_MODEL` setting, which appears only in the source (src/types.ts, src/tools/handlers.ts). Structured output is off unless `STRUCTURED_CONTENT_ENABLED` is set. It is an independent project by Tommy Nguyen (tuannvm), not published by OpenAI.
What it needs
| Runtime | Node.js |
|---|
Node.js with npx. The OpenAI Codex CLI installed separately and on PATH: v0.75.0 or later per the README (`npm i -g @openai/codex` or `brew install codex`). Codex must be signed in before use, e.g. `codex login --api-key "<OPENAI_API_KEY>"`; usage is billed to that OpenAI account.
Limits
It does nothing by itself: every tool except `ping` and `listSessions` needs the `codex` program, and fails with an authentication error until Codex is logged in. When a call resumes a session, the `sandbox`, `fullAuto` and `workingDirectory` arguments are not applied (a Codex CLI limitation noted in src/tools/definitions.ts). Sessions are held in memory only, so they are lost when the server restarts, expire after 24 hours idle and are capped at 100. Docs disagree on the minimum Codex version (README 0.75.0, API reference 0.36.0) and on the default model; the code uses `gpt-5.3-codex`.
Who it suits
Suits developers already using Claude Code or another MCP client who also pay for OpenAI and want Codex as a second reviewer or worker on the same machine and repository. It runs entirely locally and inherits whatever the Codex CLI can do, so it fits people comfortable configuring Codex's own sandbox. Not a fit without an OpenAI account, for hosted setups, or where a client must not be able to run an agent that edits files. We also list other Codex wrappers (codex-mcp-server-2 from cexll); compare their tool sets before choosing.
Tools 6
codex- Runs a prompt through Codex CLI non-interactively, with optional model, reasoning effort, sandbox, full-auto, working directory and session
review- Has Codex review uncommitted changes, a diff against a base branch, or one commit
websearch- Runs a web search through Codex with search turned on; 10 results by default, up to 50
listSessions- Lists the conversation sessions this server instance holds, with turn counts and timestamps
ping- Echoes a message back to check the connection
help- Returns the output of codex --help