How to Migrate from Codex MCP Server to App Server

OpenAI Has Deprecated the Codex MCP Server Command

If you use OpenAI Codex as an MCP server, there is an important change to make now. OpenAI's August 24, 2026 release notes say the codex mcp-server command is deprecated and recommend using the Codex app server instead. OpenAI also points Claude Code users toward the Codex plugin for Claude Code. :contentReference[oaicite:0]{index=0}

This is more than a renamed command. The two approaches expose different integration surfaces, so developers who have built custom tooling around codex mcp-server should understand the new app-server workflow before changing their integration.

What Is Changing?

The older MCP-server approach lets an MCP client launch Codex through codex mcp-server and communicate through the Model Context Protocol. OpenAI's Codex repository documents that interface as experimental and describes it as a JSON-RPC API running over MCP's standard stdio transport. :contentReference[oaicite:1]{index=1}

The recommended app-server approach exposes Codex through its own JSON-RPC protocol. The current app-server documentation supports stdio, WebSocket, and Unix-socket transports, with stdio using newline-delimited JSON. :contentReference[oaicite:2]{index=2}

Why the App Server Is Different

The app server is designed around Codex conversations rather than simply exposing Codex as another MCP tool. Its API includes operations for starting, resuming, forking, reading, and listing threads, as well as starting and controlling turns. :contentReference[oaicite:3]{index=3}

That distinction matters when you build an application around Codex. Instead of treating the model as a single MCP tool call, your client can maintain a Codex thread and interact with its lifecycle directly.

Step 1: Start the Codex App Server

The simplest integration pattern is to launch the app server over stdio:

codex app-server --listen stdio://

OpenAI's own Codex SDK uses this same architecture, launching the Codex binary with app-server --listen stdio:// and communicating through the process's standard input and output streams. :contentReference[oaicite:4]{index=4}

Step 2: Initialize the Connection

The first JSON-RPC request on a new app-server connection must be initialize. After the server responds, the client sends an initialized notification. Requests made before this handshake are rejected. :contentReference[oaicite:5]{index=5}

A minimal initialization request looks like this:

{
  "method": "initialize",
  "id": 1,
  "params": {
    "clientInfo": {
      "name": "my-ai-app",
      "title": "My AI App",
      "version": "1.0.0"
    }
  }
}

After receiving the initialization response, send:

{
  "method": "initialized"
}

The clientInfo values identify your application to the server and can be changed to match your own integration.

Step 3: Start a Codex Thread

Once the handshake is complete, create a conversation with thread/start. The app-server documentation shows that a thread can include settings such as the model, working directory, approval policy, and sandbox configuration. :contentReference[oaicite:6]{index=6}

{
  "method": "thread/start",
  "id": 10,
  "params": {
    "cwd": "/path/to/project",
    "approvalPolicy": "never",
    "sandbox": "workspaceWrite"
  }
}

The response gives your client a thread identifier. Keep that identifier if your application needs to continue the same Codex conversation later.

Step 4: Send Work with turn/start

After creating or resuming a thread, use the turn API to submit the next piece of work. The app-server then streams lifecycle and item notifications back to the client while the turn runs. OpenAI's documentation describes the thread and turn APIs as the core primitives for driving a Codex conversation. :contentReference[oaicite:7]{index=7}

This makes the architecture easier to reason about: initialize the connection, start or resume a thread, start a turn, then consume the resulting events.

Step 5: Handle the Event Stream

Do not build your client around a single response and assume the conversation is finished. The app server emits notifications for thread, turn, and item lifecycle events. Clients should continue reading the transport while the turn is running. :contentReference[oaicite:8]{index=8}

This is particularly important for applications that display live progress, tool calls, command execution, file changes, or agent messages to users.

What About Claude Code?

If your goal is specifically to use Codex from Claude Code, OpenAI's latest release note recommends the Codex plugin for Claude Code rather than continuing to launch codex mcp-server directly. :contentReference[oaicite:9]{index=9}

This is a useful distinction. A custom application that embeds Codex may want the app-server protocol, while a developer who simply wants Codex available inside Claude Code should follow the integration path OpenAI now recommends.

Why You Should Migrate Instead of Ignoring the Change

The old MCP interface was already described by the Codex project as experimental and subject to change. Its documentation identifies codex mcp-server as the server binary for that interface. :contentReference[oaicite:10]{index=10}

There are also practical reasons to avoid building new infrastructure around the deprecated path. Codex's public issue tracker contains reports involving process accumulation and lifecycle problems around MCP-server and app-server integrations, including a recent report describing stdio MCP processes accumulating during a long-lived app-server session. These reports are community issues rather than proof that every installation is affected, but they reinforce the value of moving toward the currently recommended integration surface. :contentReference[oaicite:11]{index=11}

Common Migration Mistakes

Using the Old Command in New Integrations

If you are starting a new project, there is little reason to design around codex mcp-server now that OpenAI has marked it deprecated.

Skipping the Initialization Handshake

The app server expects one initialization request per connection followed by the initialized notification. Calling thread methods before that handshake can produce initialization errors. :contentReference[oaicite:12]{index=12}

Treating App Server Like MCP

Although both systems use JSON-RPC-style communication, the app server has its own protocol and lifecycle. Your integration should be designed around threads, turns, notifications, approvals, and the app-server schema rather than assuming that MCP tool discovery works unchanged.

Ignoring Version-Specific Behavior

Codex is changing quickly, and the app-server interface itself contains experimental capabilities. Check the documentation that matches the Codex version you deploy rather than copying an old integration indefinitely. The official protocol documentation explicitly warns that experimental methods and fields can require capability opt-in. :contentReference[oaicite:13]{index=13}

A Practical Migration Plan

1. Find every place where your project launches codex mcp-server.
2. Determine whether the integration is a custom MCP client, an IDE integration, or Claude Code.
3. For custom clients, evaluate the codex app-server protocol.
4. For Claude Code, evaluate the Codex plugin recommended by OpenAI.
5. Implement the app-server initialization handshake.
6. Replace MCP-style invocation with thread and turn lifecycle handling where necessary.
7. Test approvals, sandbox settings, tool calls, streaming events, and session recovery.
8. Only remove the old MCP integration after the replacement works reliably.

The Bigger Picture

The deprecation is a sign that Codex integrations are moving toward a richer agent-runtime model. Instead of exposing Codex primarily as a single MCP endpoint, the app server provides a protocol for managing persistent threads, turns, events, approvals, and other parts of the agent lifecycle. :contentReference[oaicite:14]{index=14}

For developers building AI-powered products, that shift is worth paying attention to. Agent integrations increasingly need more than a request-and-response API: they need state, long-running work, permissions, streaming events, and predictable lifecycle management.

Frequently Asked Questions

Is codex mcp-server removed immediately?

OpenAI's August 24 release note says the command is deprecated. That means developers should begin migrating rather than treating the existing command as the long-term integration path. :contentReference[oaicite:15]{index=15}

What should replace codex mcp-server?

For custom Codex integrations, OpenAI recommends the Codex app server. For using Codex from Claude Code, OpenAI specifically points users to the Codex plugin for Claude Code. :contentReference[oaicite:16]{index=16}

Does the app server use JSON-RPC?

Yes. The app-server protocol uses JSON-RPC-style messages, with stdio providing newline-delimited JSON communication. :contentReference[oaicite:17]{index=17}

Can I still use MCP with Codex?

Yes. The deprecation concerns the command that runs Codex itself as an MCP server. The app server can still interact with MCP servers as part of Codex's broader tool ecosystem. :contentReference[oaicite:18]{index=18}

Bottom Line

If your AI development workflow currently depends on codex mcp-server, August 24's change is a good reason to review the integration now. The recommended destination is the Codex app server for custom applications, while Claude Code users should follow OpenAI's Codex plugin path. The migration requires more than changing one command, but the app-server model gives developers a more direct way to manage Codex threads, turns, events, and agent workflows.