Codex MCP Server Deprecation: App Server Migration Guide

The short answer

OpenAI has deprecated the codex mcp-server command for new integrations. The supported direction is now the Codex App Server for rich, first-class product integrations, or the Codex plugin for Claude Code when Claude Code is the host. Existing MCP-based integrations may continue to work for a transition period, but they should be treated as migration work rather than a long-term architecture.

The practical distinction is simple:

• Use Codex SDK for bounded automation, CI jobs, and background tasks.
• Use Codex App Server when your product needs threads, turns, streamed events, approvals, authentication, and conversation history.
• Use the Codex plugin for Claude Code when Codex should be called from Claude Code.
• Do not start new integrations around codex mcp-server.

This guide explains what changed, how to choose the replacement, and how to migrate without weakening sandbox or approval controls.

What OpenAI changed

OpenAI’s current documentation labels the “Use Codex with the Agents SDK” MCP-server path as deprecated. The page still documents codex mcp-server for existing integrations, but explicitly directs developers to the Codex App Server instead. It also points Claude Code users to the Codex plugin, which uses the App Server underneath.

The change is not merely a rename. MCP exposes Codex as a tool-oriented server: a client discovers tools, invokes one, and receives a result. That model is useful for simple delegation, but it does not naturally represent a persistent coding-agent product with streamed file edits, approval prompts, thread history, interruptions, and rich progress events.

The App Server is designed around those higher-level primitives. OpenAI’s open-source implementation describes a hierarchy of threads, turns, and items. A thread is the durable conversation, a turn is one agent run, and items represent messages, commands, edits, tool activity, and other events that make up the run.

Migration visual — control-plane choice

diagram

This is an original decision diagram based on OpenAI’s current Codex documentation and repository architecture. It is not an official OpenAI diagram.

Why MCP is no longer the best full-fidelity boundary

MCP remains useful in Codex: the App Server can work with MCP servers, and Codex can still consume external tools. The deprecated part is specifically exposing the entire Codex agent as an MCP server through the codex mcp-server command.

That boundary loses important information. A tool call usually wants a compact request and response. A coding agent needs a lifecycle:

1. Create or resume a thread.
2. Start a turn with user input and execution settings.
3. Stream progress and side effects.
4. Ask for approval when policy requires it.
5. Continue after approval or interruption.
6. Persist the resulting messages, edits, and status.

Trying to compress that lifecycle into one MCP tool creates awkward session conventions and makes clients responsible for reconstructing product-level behavior. The App Server makes the lifecycle explicit through JSON-RPC methods and notifications.

OpenAI’s App Server documentation describes it as the interface used by rich clients such as the Codex VS Code extension. The open-source repository documents stdio as the default transport, with WebSocket and Unix socket options. WebSocket support is marked experimental, so production deployments should follow the current documentation rather than assuming every transport has the same maturity.

For a broader view of agent runtime design, see the OpenAI Codex open agent harness guide. The App Server is the product-facing protocol; the harness is the execution foundation behind the agent.

Choosing the replacement

The key decision is whether Codex is merely a worker or a visible part of your application. A worker can fit the SDK. A visible, persistent agent belongs behind the App Server.

Migration path from codex mcp-server

1. Inventory what the old integration actually uses

Before changing code, record which parts of the MCP surface your client consumes:

• Does it only call codex and wait for text?
• Does it resume sessions through codex-reply?
• Does it depend on approval-policy, sandbox, model, working-directory, or configuration overrides?
• Does it need streamed progress, command execution, file edits, or usage data?
• Does it run locally over stdio, or does it expose a network service?

The old documentation lists tool properties such as prompt, cwd, model, sandbox, and approval-policy. Those settings do not disappear; they move into the appropriate App Server or SDK request fields.

2. Select the protocol boundary

For a product integration, use the App Server. Start it locally with the documented command:

1codex app-server

The default mode uses newline-delimited JSON over stdio. A client sends JSON-RPC messages and reads responses and notifications from the process. The App Server protocol requires initialization before other requests, then exposes thread and turn operations.

For CI or one-shot automation, do not recreate the App Server lifecycle unnecessarily. Use the Codex SDK or the documented non-interactive execution path, with a narrowly scoped working directory and sandbox policy.

For Claude Code, install and configure the Codex plugin rather than starting a second Codex MCP server manually. This keeps the integration aligned with OpenAI’s supported host path.

3. Map tool calls to thread and turn operations

A common old flow looks like this:

1MCP client -> tools/call(name=codex, prompt=...) -> text result
2MCP client -> tools/call(name=codex-reply, session=...) -> text result

The App Server flow is lifecycle-oriented:

1client -> initialize
2client -> initialized
3client -> thread/start
4client -> turn/start
5server -> item/started and progress notifications
6server -> approval request when policy requires it
7server -> item/completed notifications
8server -> turn/completed

The exact request schemas are versioned with the Codex binary. OpenAI’s repository provides the authoritative protocol README and commands for generating TypeScript or JSON Schema artifacts from the installed version:

1codex app-server generate-ts --out ./generated/codex
2codex app-server generate-json-schema --out ./generated/codex

Generate schemas in CI and review changes when upgrading Codex. Do not hand-copy a schema from an unrelated release.

4. Preserve execution controls

A migration is not complete if it preserves functionality but broadens authority. Carry forward the old integration’s controls explicitly:

• Use read-only when the agent only needs inspection.
• Use workspace-write for controlled edits in an isolated checkout.
• Avoid danger-full-access unless the deployment has a separately reviewed threat model.
• Keep approval policy at on-request for workflows that can modify files, run commands, or affect external systems.
• Restrict cwd to a dedicated workspace rather than a home directory or shared filesystem.
• Do not put bearer tokens in command-line arguments or committed configuration.

OpenAI’s App Server documentation recommends environment-based handling for remote authentication and warns that plain WebSockets should be limited to localhost or an SSH-forwarded connection. For a non-local deployment, use TLS and an authenticated channel.

These controls complement, rather than replace, the MCP security practices in the MCP tool-server threat-modeling guide. An App Server can orchestrate powerful actions; it does not make untrusted tools safe by itself.

5. Add backpressure and reconnect behavior

The open-source App Server README documents bounded queues and a retryable overload error. Clients should treat a server-overloaded response as temporary and retry with exponential backoff plus jitter. They should also distinguish a dropped transport from a completed turn.

A robust client should persist enough state to answer these questions after reconnecting:

• Which thread was active?
• Which turn was in progress?
• Was an approval request outstanding?
• Which events were acknowledged?
• Did the server finish, fail, or get interrupted?

Do not blindly replay a turn after a network failure. A replay can duplicate file edits or external side effects. Prefer a status query or explicit resume operation when supported by the installed App Server version.

A minimal stdio client shape

The following example is intentionally a protocol outline rather than a copy-paste SDK. The method names and payload details must be generated or checked against the Codex version you deploy.

1import json
2import subprocess
3
4proc = subprocess.Popen(
5    ["codex", "app-server"],
6    stdin=subprocess.PIPE,
7    stdout=subprocess.PIPE,
8    text=True,
9    bufsize=1,
10)
11
12def send(message: dict) -> None:
13    proc.stdin.write(json.dumps(message) + "\n")
14    proc.stdin.flush()
15
16send({
17    "id": 1,
18    "method": "initialize",
19    "params": {
20        "clientInfo": {
21            "name": "example-integration",
22            "title": "Example Integration",
23            "version": "0.1.0",
24        }
25    },
26})
27send({"method": "initialized"})
28// Continue with thread/start and turn/start after validating the response.

For production, add bounded reads, process-health checks, structured logging to stderr, shutdown handling, and a schema-validated message layer. If the integration is written in TypeScript, generate the version-matched types instead of treating JSON as untyped application data.

What changes for MCP clients

If your current host is an OpenAI Agents SDK application that starts codex mcp-server, separate two concerns:

1. Codex as the primary agent runtime. Migrate the host-to-Codex boundary to the App Server or SDK.
2. External tools used by Codex. Keep those tools as MCP servers where appropriate and configure them in Codex.

Do not confuse the deprecation with a shutdown of MCP support. The official Codex App Server repository documents MCP extension profiles and downstream MCP initialization. MCP remains a useful interoperability layer for tools and services; it is simply no longer the recommended wrapper for the full Codex product lifecycle.

If your application only needs a single text answer from Codex and does not need persistence, approvals, or event streaming, the SDK is usually simpler. If your application renders an agent timeline, displays diffs, or lets a human approve commands, the App Server is the better fit.

The OpenAI Agents SDK MCP v2 guide is useful background for the opposite direction: integrating MCP tools into an agent application. This migration is about choosing the right boundary in the other direction.

Common migration mistakes

Treating deprecation as an immediate outage

OpenAI still documents the old page for existing integrations. That does not make it the right foundation for new work. Create a migration issue, pin the current Codex version, and test the replacement before upgrading production.

Assuming App Server is just another MCP endpoint

It is JSON-RPC-based, but the lifecycle is different. Build around initialization, threads, turns, notifications, approvals, and completion states—not a single tools/call response.

Reusing unsafe defaults

A migration is a good time to reduce authority. Avoid copying a legacy danger-full-access setting just because it was present in a development command.

Parsing human-readable output

Use structured protocol messages and generated schemas. Human-readable terminal output is not a stable integration contract.

Exposing WebSocket listeners without a threat model

The repository marks WebSocket transport as experimental. If you expose a listener remotely, use TLS, authentication, origin protections, network controls, and an explicit review of what a connected client may do.

Replaying requests after disconnects

A coding turn can have side effects. Reconnect logic must distinguish unknown completion from confirmed failure and should favor inspection or resume over blind replay.

FAQ

Is codex mcp-server removed immediately?

The current OpenAI documentation calls it deprecated and retains the page for existing integrations. The safe interpretation is to stop starting new projects with it and plan migration rather than rely on an undocumented removal date.

Should I use the Codex App Server or SDK?

Use the SDK for bounded jobs and CI. Use the App Server for a persistent product integration with threads, approvals, streaming, and rich agent events.

Should Claude Code users configure the App Server manually?

OpenAI’s documentation directs Claude Code users to the Codex plugin for Claude Code. Prefer that supported path unless you have a specific reason to own the lower-level protocol integration.

Does this deprecation mean MCP is no longer supported by Codex?

No. MCP remains the tool and service interoperability layer. The deprecated command is the old way of exposing the complete Codex agent as an MCP server.

Where should I verify protocol details?

Use the Codex App Server documentation, the deprecated MCP-server documentation for old behavior, and the openai/codex App Server README matching the exact version you deploy.

Conclusion

OpenAI’s codex mcp-server deprecation is a boundary correction. MCP is excellent for exposing tools and services, but a full coding-agent product needs a protocol that represents persistent threads, streamed turns, approvals, edits, and recovery. That is the role of the Codex App Server.

For new work, choose deliberately: SDK for bounded automation, App Server for rich product integrations, and the Codex plugin for Claude Code. For existing MCP wrappers, inventory the behavior, map tool calls to the thread/turn lifecycle, preserve sandbox and approval controls, generate version-matched schemas, and test reconnect behavior before rollout.

Sources and visual credits

• OpenAI Codex App Server documentation — primary implementation guidance and transport/security notes.
• OpenAI deprecated Codex MCP-server documentation — primary record of the deprecation and replacement recommendation.
• OpenAI Codex App Server README — open-source protocol, lifecycle, transport, and backpressure details.
• OpenAI Codex releases — version and release-history verification.
• Mermaid decision diagram: original editorial illustration by Essa Mamdani, based on the primary OpenAI documentation and repository.

Related reading

Continue exploring related AI engineering and developer tooling topics:

• Spring Tools 5.2.0: Claude Code, Embedded MCP, and Safer Spring Boot Workflows
• X Ads MCP: A Safe Developer Guide to AI-Powered Campaign Management
• agent-device: Give AI Coding Agents a Mobile App Feedback Loop