# codex-mcp-server: wiring OpenAI's Codex CLI into Claude Code over MCP > A TypeScript MCP server that exposes the Codex CLI as tools inside Claude Code, Cursor and other MCP clients. It is a thin bridge, and the thinness is both the point and the limitation. **tuannvm/codex-mcp-server** — MCP server wrapper for OpenAI Codex CLI that enables Claude Code to leverage Codex's AI capabilities directly. - Repository: https://github.com/tuannvm/codex-mcp-server - Website: https://docs.tuannvm.com/codex-mcp-server - Stars: 641 · Forks: 80 - Language: TypeScript - License: not declared - Published: 2026-09-10 · Updated: 2026-09-10 · Language: en - Canonical page: https://hysenlabs.com/projects/tuannvm-codex-mcp-server ## The gap codex-mcp-server fills between Claude Code and Codex CLI Claude Code speaks MCP. The Codex CLI does not. Those two facts are the whole reason this project exists. Codex CLI is a terminal program you authenticate once and then drive by hand; Claude Code is an agent that can call any tool an MCP server advertises. Without a wrapper, an engineer who wants Codex's opinion on a diff has to leave the editor, run the CLI, and paste the result back. The server closes that loop by registering Codex as a set of MCP tools the client can invoke on its own. The audience is narrow and specific. You need to already be a Claude Code user, or a Cursor user, or someone running another MCP-capable client. You need an OpenAI API key. You need to be comfortable with a Node toolchain, because the server is distributed on npm as codex-mcp-server and runs through npx. If you only want Codex, install Codex. This project is for people who want both agents reachable from one prompt box. ## How the bridge works: MCP tools in front, Codex CLI behind The README's architecture diagram is a straight line: Claude Code to Codex MCP Server to Codex CLI to the OpenAI API. Nothing is proxied through a hosted service. The server runs locally, the CLI runs locally, and only the final hop leaves the machine. The server is a TypeScript program built on @modelcontextprotocol/sdk, with zod for parameter validation and chalk for terminal output. It exposes six tools according to the README's table: codex, review, websearch, listSessions, ping and help. The codex tool is the general-purpose one and carries the interesting options: session support, model selection, reasoningEffort, fullAuto, sandbox, and a callbackUri. The review tool targets uncommitted changes, a branch, or a commit range. websearch takes a query plus numResults and searchDepth. The transport is stdio, which is why the install snippets pass a command and args rather than a URL. Sessions are held per server instance. The README is explicit that passing a sessionId creates the session on first use, so listSessions will show it for that instance and later calls can resume context. That qualifier matters: the session lives with the process, not in a shared store. One environment variable is documented, CODEX_MCP_CALLBACK_URI, described as a static MCP callback URI passed to Codex when set, overridden by the callbackUri tool argument. The README does not explain what the callback is used for beyond that. ## Installing codex-mcp-server and running a first review The README splits setup into two steps, and the order matters: the wrapper is useless until the CLI underneath it is authenticated. First install the Codex CLI globally and log in with an API key. ```bash npm i -g @openai/codex codex login --api-key "your-openai-api-key" ``` The README also lists brew install codex as an alternative to the npm install. After login, the CLI should be usable on its own. Second, register the server with Claude Code. The README gives a single command, which adds a stdio server named codex-cli that npx launches on demand. ```bash claude mcp add codex-cli -- npx -y codex-mcp-server ``` Once that is in place, the tools appear in the client and you drive them in natural language. A first real use is the review tool against local edits, which the README demonstrates with an uncommitted flag. ```text Use review with uncommitted true to review my local changes ``` For a branch comparison, the README shows a base argument instead: review with base "main" to check PR changes. If you would rather check the wiring before trusting it with a diff, the ping tool exists for exactly that, and help returns Codex CLI help text. The README also offers one-click install badges for VS Code, VS Code Insiders and Cursor. Those encode the same stdio config, with command npx and args ["-y", "codex-mcp-server"], so a client that supports the badge URL can skip the manual step. ## Where codex-mcp-server is the wrong tool The dependency chain is the first constraint. The README requires Codex CLI v0.75.0 or later. If your installed CLI is older, the wrapper will not have a working backend, and the failure will surface as a tool error rather than a clear version complaint. Pin and check the CLI version before you file anything against this repository. The second constraint is authentication. This server does not hold credentials. It shells out to a CLI that was logged in separately. That means the MCP client's permissions and the Codex CLI's permissions are two different things, and the API key lives wherever codex login put it. A team that wants per-user API keys through a single editor config will not get that here. The third is scope. This is a wrapper, not an agent. It adds no reasoning of its own, no caching layer, no retry policy documented in the README, and no cost control. Every codex call is an OpenAI API call billed to the account behind the CLI. If your concern is runaway spend from an agent that decides to call a model tool repeatedly, nothing in the documented surface stops that. Use the CLI directly when you want a single deliberate invocation, and skip the wrapper when the editor is not where you work. Finally, if your client is not MCP-capable, this project has nothing to offer you. It is a bridge between two specific things. ## gemini-mcp-server and the difference in what sits behind the bridge The README points to gemini-mcp-server from the same author as a related project, and the comparison is instructive because the shape is identical while the payload is not. Both are MCP servers that wrap a vendor CLI, both install through npm, both run over stdio, and both expose the underlying CLI's capabilities as tools to an MCP client. The difference is the backend and what it brings. The README describes gemini-mcp-server as an MCP server for Gemini CLI with 1M+ token context, web search, and media analysis. That is a claim about the underlying model's context window and modality, not about the wrapper. codex-mcp-server inherits whatever Codex CLI offers, which per this README includes a websearch tool with configurable result count and search depth, plus model and reasoningEffort selection on the codex tool. So the choice is not architectural. If you are already paying for one vendor's API, or you have a codebase whose size pushes against context limits, that decides it. Swapping wrappers is cheap; swapping the model behind them is the real decision. The two servers are close enough in interface that the migration cost is mostly re-authenticating a different CLI. ## Maintenance, licence and what upgrading actually costs The repository is not archived. Its last push was on 2026-05-25, roughly four months before this writing, and the most recent release listed is v1.4.10 from 2026-04-10. That is a real gap between the last release and the last commit, and it is worth reading as what it is: the project is not dormant, but it is also not shipping weekly. Treat the release cadence as the thing to check before you depend on a fix arriving quickly. The licence situation is worth a second look. The README ends with a License section reading ISC, and package.json carries "license": "ISC". The repository metadata supplied for this review lists the licence as unknown. The two sources disagree, and the npm badge the README displays reads the licence from the published package. If licence terms matter to your organisation, read the LICENSE file in the repository rather than trusting either summary. This is not legal advice. Upgrade cost is low but not zero. The package is published to npm and the README's install path runs npx -y codex-mcp-server, which fetches the latest version each time the client starts the server unless you pin. That means an upgrade can arrive without you choosing it. The server also tracks Codex CLI behaviour: the README has a section on Codex 0.87 compatibility describing threadId handling, structuredContent, and an advertised outputSchema for structured responses. When the CLI changes its output shape, the wrapper has to follow. If you need reproducibility, pin the package version in your MCP client config instead of relying on npx's default resolution. ## Conclusion Adopt codex-mcp-server if you already run Claude Code or Cursor and want Codex's CLI available as a callable tool without leaving the editor, and if you accept that every invocation consumes OpenAI API quota through a separately authenticated Codex CLI. Do not adopt it as a way to get Codex without Codex, or in an environment where you cannot install a global npm package and run codex login. Verify first that your Codex CLI reports v0.75.0 or later, since the README states that as a hard requirement, and check the API reference for the exact parameter shapes of the codex and review tools before you script anything against them. ## FAQ ### What is codex-mcp-server? It is an MCP server that wraps the OpenAI Codex CLI so MCP clients such as Claude Code and Cursor can call Codex as a tool. The README describes it as a bridge that exposes code analysis, generation and review inside your editor. ### How do I set up codex-mcp-server? Install the Codex CLI with npm i -g @openai/codex, authenticate with codex login --api-key, then register the server using claude mcp add codex-cli -- npx -y codex-mcp-server. The README requires Codex CLI v0.75.0 or later. ### How do I add codex-mcp-server to Claude Code? The README gives one command: claude mcp add codex-cli -- npx -y codex-mcp-server. It registers a stdio server named codex-cli that npx launches. ### Can I use codex-mcp-server in VS Code? Yes. The README provides VS Code and VS Code Insiders one-click install badges whose config uses type stdio, command npx and args ["-y", "codex-mcp-server"]. Cursor has an equivalent badge. ### How do I use codex-mcp-server for a code review? The README shows the review tool with two modes: review with uncommitted true for local changes, and review with base "main" to check branch or PR changes. The codex tool handles general analysis and generation. ## Sources - [Issues](https://github.com/tuannvm/codex-mcp-server/issues) - [Project website](https://docs.tuannvm.com/codex-mcp-server) - [README](https://github.com/tuannvm/codex-mcp-server/blob/main/README.md) - [Releases](https://github.com/tuannvm/codex-mcp-server/releases) - [tuannvm/codex-mcp-server on GitHub](https://github.com/tuannvm/codex-mcp-server) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/tuannvm-codex-mcp-server