Codex Deprecated Its MCP Server, Not MCP. The Direction of That Cut Is the Story

On August 24 OpenAI deprecated the codex mcp-server command. The same Codex release shipped roughly fifteen pull requests improving how Codex consumes other people's MCP servers. Here's what that asymmetry tells you about where the protocol actually fits, and what to change in your setup this week.

The changelog entry is three sentences long. "The codex mcp-server command is now deprecated. Use the Codex app server instead. To use Codex from Claude Code, use the Codex plugin for Claude Code." No rationale, no removal date, no migration guide beyond two links (OpenAI changelog, August 2026).

Read it next to the rest of that release and it gets stranger. Codex CLI 0.149.0, which shipped the deprecation warning four days earlier, also carried something like fifteen pull requests hardening Codex's MCP client: OAuth fixes, redirect restrictions, tool-name length limits, hooks that call MCP tools. Codex adding external MCP servers through codex mcp add and [mcp_servers.<name>] config tables is completely untouched (Codex MCP docs).

So one company, in one release, narrowed its use of a standard in one direction and widened it in the other. That is not a vote against MCP. It is a vote about which half of MCP was load-bearing, and I think they got it right.

The thing MCP was never shaped to do

Here's my position, stated plainly: MCP is a good protocol for handing an agent a tool, and a bad protocol for handing someone an agent. The deprecation is the first time a major vendor has said that out loud with a shipping decision rather than a blog post.

Think about what codex mcp-server was for. It let another program (Claude Code, an IDE, a script) speak MCP at Codex and get Codex's abilities back as tools. Neat idea. The problem is that "run a coding agent for me" is not a function call that returns a value. It is a long-lived session with a conversation history, streaming output, a diff that changes shape while you watch, and a moment partway through where the agent stops and asks whether it may write to a file.

MCP models the first half of that fine and the second half badly. OpenAI said so back in February, in a post about how the app server got built:

"We first experimented with exposing Codex as an MCP server, but maintaining MCP semantics in a way that made sense for VS Code proved difficult."

and, in the same piece:

"The downside is that you only get what MCP exposes, so Codex-specific interactions that rely on richer session semantics (e.g., diff updates) may not map cleanly through MCP endpoints."

(OpenAI, "Unlocking the Codex harness", February 4, 2026)

That post is six months older than the deprecation, and it still recommended codex mcp-server as a valid path for MCP-based workflows. August is when the recommendation flipped. The reasoning didn't change; the patience ran out.

What the app server actually is

The replacement is codex app-server, and its shape tells you exactly which gaps were being papered over.

It speaks JSON-RPC 2.0, bidirectionally, over newline-delimited JSON on stdio. Almost MCP, and deliberately close: the repo README says as much, noting only that the "jsonrpc":"2.0" header is omitted on the wire (app-server README). A websocket transport exists and is marked experimental. There's a unix socket option too.

The primitives are where it diverges. Three of them: Thread, Turn, Item. You call thread/start, or thread/resume against an existing one, or thread/fork to branch. Inside a thread you call turn/start, and the server streams item/started, then item/*/delta messages as work lands, then item/completed, then turn/completed. The server can interrupt its own turn to ask you for an approval, and the turn pauses until you answer.

Look at that list again. Resume. Fork. Streaming deltas. Server-initiated approval that blocks progress. Every one of those is a session concept, and none of them lives comfortably inside "client calls tool, tool returns result." You can bolt each on individually. You cannot make the sum of them feel native.

The clean way to say it: Codex stopped serving MCP. It did not stop speaking MCP. Consuming a tool is a request and a response, and the protocol is great at that. Driving an agent is a conversation with a lifecycle, and it isn't.

The plugin nobody reads carefully

The second link in that changelog entry is the one people skim past. OpenAI's recommended way to drive Codex from Claude Code is now openai/codex-plugin-cc, an Apache-2.0 Claude Code plugin sitting at roughly 32,300 stars.

Go read its README and you find this: "The Codex plugin wraps the Codex app server... It uses the global codex binary installed in your environment." The plugin ships no MCP server of its own. It shells out to a local binary and talks the app server's JSON-RPC.

That detail deserves a beat. Anthropic's plugin system was designed with MCP servers as one of its four bundled extension points, alongside slash commands, subagents, and hooks (Claude Code plugins). OpenAI's flagship plugin for Anthropic's tool uses zero of that MCP capacity. Cross-vendor agent-to-agent control just moved from a shared protocol to a bilateral, first-party integration, and it moved inside the packaging format built to distribute the protocol.

Both companies landed on "plugin as the unit of distribution." Only one of them walked a protocol back to get there.

Put this into practice

Three cases, in rising order of effort.

You consume MCP servers from inside Codex. Do nothing. This is most people. codex mcp add, codex mcp list, codex mcp login, the config tables, OAuth, per-tool approval modes: all current, all actively maintained. If a headline made you think Codex dropped MCP, that headline was wrong.

You drive Codex from Claude Code. Install the plugin and stop maintaining your own bridge. /plugin marketplace add openai/codex-plugin-cc, then /plugin install codex@openai-codex, then /codex:setup. You get /codex:review for read-only review against a base ref, /codex:adversarial-review when you want to point it at something specific, /codex:rescue to hand a stuck task to a Codex subagent, and /codex:transfer to mint a persistent Codex thread out of your current Claude Code transcript. Node 18.18 or newer, and usage bills against your Codex limits.

You wrote your own client against codex mcp-server. Grep your CI configs, your dotfiles, and your internal tooling for that string today. The command still runs, but since 0.149.0 it prints "deprecated and will be removed in a future release" on launch (PR #39657). Port to codex app-server --stdio. Before you write a line of glue, run codex app-server generate-ts or generate-json-schema to emit the type definitions for the exact version you have installed. The schema is generated per-version, which is a strong hint about how much churn to expect.

The cheapest first step for anyone: run codex --version, then launch your existing integration once and read stderr. If the warning is there, you have a clock running that has no published deadline.

Honest limitations

The stability story is a mess, and I'd rather say so than pick the flattering half.

OpenAI's own two sources disagree about what the app server is. The docs page states, flatly, that "the app-server command and WebSocket transport are experimental and aren't supported for production workloads" (app server docs). The February engineering post calls it "the first-class integration method we maintain moving forward" and says the JSON-RPC surface "is designed to be backward compatible, so older clients can talk to newer servers safely." The GitHub README splits the difference again, labeling only the websocket transport experimental while gating a long list of individual methods behind an experimentalApi capability flag. That sentence in the docs sits at the end of a section about remote hosts, so it might be scoped to websockets. As written, it names the command. I could not resolve which reading is intended, and you should not build a production dependency on the assumption that it's the generous one. The docs also point CI and automation users at the Codex SDK rather than the app server, which is its own signal.

There is no removal date for codex mcp-server. "A future release" is all anyone has said.

There is no rationale published alongside the deprecation. Everything I quoted above about MCP semantics comes from February. If you see a piece claiming OpenAI explained itself on August 24, it's filling a gap with inference.

Performance is not cited anywhere as a motive. I looked for it. It isn't there.

And the tempting story is wrong. MCP shipped a large breaking revision on 2026-07-28 that removed the initialize handshake, removed protocol-level sessions and the Mcp-Session-Id header, replaced server-initiated requests with a Multi Round-Trip Requests mechanism, and deprecated Roots, Sampling, and Logging (spec changelog). Four weeks before this deprecation. It would make a tidy narrative, and no source connects the two. OpenAI's stated reasoning predates the revision by half a year, and Codex reportedly adopted the new revision as a client. "OpenAI walked away because MCP changed" is a story I can't support, so I'm not telling it.

One practical warning while you're checking any of this yourself. The developers.openai.com/codex/changelog page currently serves stale content ending in June; the live one is at learn.chatgpt.com/docs/changelog, and most Codex doc pages have a plain Markdown twin at <url>.md. GitHub's own HTML is also serving badly cached star counts right now. An uncached API read for codex-plugin-cc gave me 19,978 and a cache-busted read gave 32,307 minutes apart. Use the second one.

What to take from it

Watch which direction protocol cuts run. A vendor dropping a standard entirely is a story about the standard. A vendor dropping one half while investing in the other is a story about a boundary, and boundaries are more useful than verdicts.

The boundary here looks like this: if the thing you're exposing returns a value, expose it over MCP and let every agent in the ecosystem reach it. If the thing you're exposing is an agent with a session, a lifecycle, and a human in the approval path, you are going to end up writing a protocol, and you should plan for that instead of discovering it in month six.

Go look at what you've built on top of codex mcp-server. Then ask the harder question about your own tools: are you shipping a function, or are you shipping a conversation? The answer decides whether MCP is your integration layer or your ceiling.

Sources: OpenAI Codex changelog, deprecated MCP server page, Codex app server docs, app-server README, Codex MCP client docs, openai/codex PR #39657, Unlocking the Codex harness, openai/codex-plugin-cc, Claude Code plugins, MCP 2026-07-28 spec changelog.