codex-mcp-server: wrapping the Codex CLI as an MCP tool for Claude Code
MCP server wrapper for OpenAI Codex CLI that enables Claude Code to leverage Codex's AI capabilities directly.
At a glance
- What is it?
- An ISC-licensed TypeScript MCP server that shells out to the OpenAI Codex CLI so Claude Code, Cursor and other MCP clients can call Codex tools. It is a thin bridge, and its limits are the limits of the CLI it wraps.
- Who is it for?
- Adopt it if you already run the Codex CLI and want its code review and web search reachable from Claude Code or Cursor without leaving the editor. Skip it if you want a self-contained analyser, if you cannot install a global npm package and authenticate Codex on every machine, or if you need sessions to survive an MCP server restart.
- Can I use it commercially?
- Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
- Is it still maintained?
- Yes. The repository last received commits 114 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap it fills between Claude Code and the Codex CLI
Claude Code and the Codex CLI are separate programs with separate authentication and separate context. If you want a second model's opinion on a diff, the manual route is to leave the editor, run codex in a terminal, paste the code, and copy the answer back. This project removes that round trip by exposing the CLI as MCP tools. The audience is narrow and specific: developers who already have an OpenAI API key, already run Claude Code or Cursor, and want Codex's analysis available as a tool call rather than a separate window. It is not a library you import, and it does not reimplement any model inference. Everything it does, the Codex CLI already did.
Six tools, one of which does the work
The README lists six tools: codex, review, websearch, listSessions, ping and help. The codex tool is the general one, taking a prompt plus optional sessionId, model, reasoningEffort, fullAuto, sandbox and callbackUri arguments. review is a preset around uncommitted changes, a branch base, or specific commits. websearch takes a query with numResults and searchDepth. listSessions reports active conversations for the current server instance, ping checks the connection, and help returns Codex CLI help text.
The architecture is a straight line, and the README's mermaid diagram draws it that way: Claude Code talks to this server over stdio, the server invokes the Codex CLI, and the CLI talks to the OpenAI API. There is no caching layer, no queue, no local model. That matters for two reasons. First, every tool call pays the latency of a CLI process plus a network round trip. Second, the server's behaviour is coupled to the CLI version on your machine, which is why the README pins a floor of Codex CLI v0.75.0.
Sessions live in the server process, not on disk
The sessionId argument is the most interesting part of the design and the easiest to misread. The README states that passing a sessionId creates the session on first use, so listSessions will show it for this server instance, and subsequent calls can resume context. The phrase for this server instance is doing real work in that sentence. Sessions are held by the running MCP server process, so restarting the server, or letting npx spin up a fresh instance, drops them. Multi-turn refactoring works within one editor session and not across a restart. If you need durable conversation history, this is the wrong tool.
Separately, the README documents Codex 0.87 compatibility: when the CLI emits a threadId, the server returns it in content metadata and structuredContent, and advertises an outputSchema. That is a one-way passthrough of an identifier the CLI produces, not a persistence mechanism on the server side. The two features are easy to conflate and are not the same thing.
Install commands and the environment variable that matters
Two install steps, both from the README. First the CLI and its authentication:
npm i -g @openai/codex codex login --api-key "your-openai-api-key"
Then register the server with Claude Code:
claude mcp add codex-cli -- npx -y codex-mcp-server
The README also offers one-click install links for VS Code, VS Code Insiders and Cursor, each encoding a stdio config with command npx and args ["-y", "codex-mcp-server"]. If you prefer to write the config yourself, that is the shape to copy.
There is exactly one environment variable documented: CODEX_MCP_CALLBACK_URI, a static MCP callback URI passed to Codex when set. The README notes it is overridden by the callbackUri tool argument, so the per-call value wins over the environment default. Everything else in the advanced examples is a tool argument rather than configuration: model "o3" with reasoningEffort "high", fullAuto true with sandbox "workspace-write", and query-level options for websearch such as numResults 15 and searchDepth "full".
fullAuto and workspace-write are the arguments to think hardest about
The README gives this example: use codex with fullAuto true and sandbox "workspace-write" for automated tasks. That combination hands the CLI permission to modify files inside the workspace without an interactive confirmation step, triggered from inside your editor. The server is not adding a policy layer on top; it forwards the flags. Any guardrail is whatever the Codex CLI itself enforces for that sandbox mode, and this repository's documentation does not restate those rules. If you enable this, you are trusting the CLI's sandbox semantics, and you should read the CLI's own documentation rather than this project's README before pointing it at a repository you care about.
The websearch tool has a similar shape. It forwards a query to Codex CLI with a result count and a search depth. What gets sent to the provider, and what is retained, is decided by the CLI and the API, not by this wrapper. The README does not describe a filtering or redaction step, and there is no evidence in the material of one.
Where the bridge approach stops being the right choice
The hard requirement is Codex CLI v0.75.0 or newer, installed globally via npm or Homebrew, with a valid OpenAI API key. That is three external dependencies before the MCP server does anything. In a locked-down environment where global npm installs are blocked, or where API keys are managed centrally rather than per developer, this project has no fallback path. It cannot run without the CLI.
A second limit is that the server adds no analysis of its own. If the Codex CLI changes a flag name, a response shape, or the threadId behaviour, the wrapper has to follow. The README's own compatibility section for Codex 0.87 is evidence that this tracking work is ongoing rather than finished. A tool that must announce compatibility with each upstream release is a tool with a maintenance tail.
The third limit is the licence. The README's final section says ISC, while the repository metadata supplied for this review lists the licence as unknown. The npm badge in the README points at an npm licence field that may or may not match. Before you vendor or redistribute this, check the LICENSE file in the repository rather than trusting either the badge or the README heading. That is a factual discrepancy, not a legal opinion.
How it differs from the sibling gemini-mcp-server
The README points to gemini-mcp-server, another MCP wrapper from the same author. The difference in approach is the underlying CLI and what that CLI exposes. The Gemini wrapper is described as offering 1M+ token context, web search and media analysis. This one is described as offering code analysis, generation and review through Codex, with a review tool that is scoped to git state (uncommitted changes, a branch base, specific commits).
The practical distinction is the review workflow. The review tool here is built around diffs and branches, which fits a pull request check. The Gemini wrapper's advertised strength is context volume and non-text media. If your task is reviewing a large diff, this project's review tool is the closer fit. If your task is feeding a very large document or an image into a model, the sibling is the closer fit. Neither replaces a linter or a type checker; both are model calls with the latency and cost that implies.
Maintenance cost and what to verify before adopting
Upgrade cost is concentrated in one place: the Codex CLI version on every developer machine. The server itself is published to npm and invoked with npx -y, so clients pick up new releases automatically, but a mismatch between the wrapper and a locally installed CLI is the failure mode the README's compatibility section is written to address. The release history shows a burst of releases in April 2026 (v1.4.2, v1.4.3, v1.4.10) and a last push in May 2026, which is consistent with active tracking of upstream changes rather than a frozen tool.
Three things to verify on your own machine before committing to it. Run the ping tool to confirm the server is reachable from your MCP client. Confirm codex --version reports at least 0.75.0 on the PATH the MCP client uses, since a GUI editor may not inherit your shell environment. And read the LICENSE file directly, because the README says ISC and the repository metadata says unknown. If those three checks pass, the bridge does what it claims; if the CLI cannot be installed globally, nothing else in this project will help.
Editorial conclusion
Adopt it if you already run the Codex CLI and want its code review and web search reachable from Claude Code or Cursor without leaving the editor. Skip it if you want a self-contained analyser, if you cannot install a global npm package and authenticate Codex on every machine, or if you need sessions to survive an MCP server restart. Before wiring it into a team workflow, run npx -y codex-mcp-server with the ping tool, confirm which Codex CLI version is on the PATH, and check the npm licence field against the ISC text in the README, because the two do not currently agree.
Community notes