Guide
Codex mcp-server Is Deprecated: A Practical App Server Migration Guide
On August 24, 2026, OpenAI deprecated the `codex mcp-server` command. The replacement depends on the actual integration goal. Deep product integrations should use the Codex App Server; CI, batch jobs, and non-interactive automation should generally use the Codex SDK; and users invoking Codex from Claude Code should use the Codex plugin for Claude Code. App Server is not simply MCP Server under a new name. It is a bidirectional Codex control protocol exposing authentication, threads, turns, approvals, streamed agent events, MCP integration, configuration, and runtime state through JSON-RPC-style messages.
# Codex mcp-server Is Deprecated: A Practical App Server Migration Guide
## Article Summary
On August 24, 2026, OpenAI deprecated the `codex mcp-server` command. The replacement depends on the actual integration goal. Deep product integrations should use the Codex App Server; CI, batch jobs, and non-interactive automation should generally use the Codex SDK; and users invoking Codex from Claude Code should use the Codex plugin for Claude Code. App Server is not simply MCP Server under a new name. It is a bidirectional Codex control protocol exposing authentication, threads, turns, approvals, streamed agent events, MCP integration, configuration, and runtime state through JSON-RPC-style messages.
---
The August 24 Codex release notes contain a small but important sunset:
```text
codex mcp-server
```
is deprecated.
OpenAIβs primary replacement for deep client integration is:
```text
codex app-server
```
The key is understanding that MCP Server and App Server solve different problems.
## MCP Server provides tools to an agent
The usual relationship is:
```text
agent client
β MCP
β tool server
```
For example:
```text
search_docs
query_database
create_ticket
```
## Codex App Server embeds Codex into your product
The architecture is more like:
```text
your product
β Codex App Server protocol
β Codex runtime
β models / tools / approvals / threads
```
MCP is a tool protocol.
App Server is a rich-client integration protocol for Codex itself.
## Why the old command became awkward
Codex now contains a broader runtime surface:
- conversation history;
- threads;
- turns;
- approvals;
- file changes;
- command execution;
- apps;
- MCP;
- plugins;
- sandboxing;
- authentication.
Compressing the entire Codex experience into βan MCP serverβ is no longer the cleanest abstraction.
## Choose the interface by workload
### Building your own IDE, desktop client, or rich Codex UI
Use:
```text
Codex App Server
```
OpenAI positions it for deep integration involving authentication, history, approvals, and streamed agent events.
### Running automation or CI
Use:
```text
Codex SDK
```
This avoids running a rich interactive protocol for batch work.
### Calling Codex from Claude Code
Use the Codex plugin for Claude Code rather than building a new dependency on the deprecated command.
## App Server uses bidirectional JSON-RPC-style messaging
A request can look like:
```json
{
"method": "thread/start",
"id": 10,
"params": {
"model": "gpt-5.6-terra"
}
}
```
A response returns the same ID:
```json
{
"id": 10,
"result": {
"thread": {
"id": "thr_123"
}
}
}
```
Notifications have no request ID:
```json
{
"method": "turn/started",
"params": {
"turn": {
"id": "turn_456"
}
}
}
```
The critical point is that App Server is not only request/response.
The server can initiate events and approval requests back to the client.
It behaves like a bidirectional agent-runtime protocol.
## stdio is the simplest local integration
Running:
```bash
codex app-server
```
uses stdio by default with newline-delimited JSON.
A local application can:
```text
spawn Codex
β write JSON to stdin
β read events from stdout
```
This is well suited to:
- IDE extensions;
- desktop apps;
- local developer tooling.
## Threads and turns are first-class
A thread represents a longer-lived work context.
A turn is an interaction inside that thread.
For example:
```text
Thread: refactor payment service
βββ Turn 1: analyze database layer
βββ Turn 2: implement repository changes
βββ Turn 3: add tests
```
This is why App Server is better suited to a full Codex user experience than a single MCP tool call.
## Approvals are part of the protocol
Depending on Codex settings, command execution and file changes may require user approval.
App Server sends a server-initiated request and the client responds with decisions such as:
```text
accept
acceptForSession
decline
cancel
```
Custom clients must treat approval UX as a core feature, not an optional afterthought.
## Do not silently auto-approve everything
A dangerous client implementation is:
```text
if approval_request:
always accept
```
That removes an important security boundary.
A better policy is:
```text
low risk β policy-based automatic approval
medium risk β user confirmation
high risk β strong confirmation or block
```
The application should own that policy.
## App Server still works with MCP servers
Deprecating `codex mcp-server` does not mean Codex is abandoning MCP.
App Server exposes methods for configured MCP infrastructure, including operations for:
- listing server status;
- calling MCP tools;
- reading MCP resources;
- OAuth login;
- reloading MCP configuration.
The new architecture is:
```text
your client
β App Server
β Codex
β configured MCP servers
```
App Server is the control surface.
MCP servers remain external tool surfaces.
## Supported transports
App Server supports:
```text
stdio
websocket
unix socket
```
WebSocket transport is currently documented as experimental and unsupported for production workloads.
Local WebSocket use can be convenient:
```bash
codex app-server --listen ws://127.0.0.1:4500
```
Remote use requires stronger controls.
## Remote security matters
For non-local connections, OpenAI recommends secure WebSockets, authentication, and TLS.
Do not expose an unauthenticated App Server listener to the public internet.
This endpoint can potentially participate in operations involving:
- code access;
- file changes;
- command execution;
- MCP tools.
Treat it as an agent control plane, not a debug port.
A safer pattern is:
```text
client
β WSS / TLS
β authenticated proxy
β Codex App Server
β sandbox / repository / MCP
```
Add network controls, auditing, and short-lived credentials.
## Backpressure must be handled
In WebSocket mode, App Server uses bounded queues.
When overloaded, it can return an error indicating the server is full and the client should retry later.
Clients should use:
```text
exponential backoff
+ jitter
```
not immediate infinite retries.
## Generate schemas from the installed Codex version
App Server can generate TypeScript or JSON Schema definitions:
```bash
codex app-server generate-ts --out ./schemas
```
or:
```bash
codex app-server generate-json-schema --out ./schemas
```
This is valuable because protocol surfaces can evolve with Codex versions.
A safe upgrade pipeline is:
```text
upgrade Codex
β regenerate schema
β type-check client
β integration tests
β release
```
## Do you actually need App Server?
Not every deprecated `mcp-server` integration should become App Server.
Use this decision tree:
### Need automation only?
Use the SDK.
### Need your own rich interactive UI?
Use App Server.
### Need to expose tools to Codex?
Build an MCP server.
### Need Codex inside Claude Code?
Use the Codex plugin.
The clearer separation is an architectural improvement.
## Migration checklist
If a project currently depends on:
```text
codex mcp-server
```
review:
1. Who is the current client?
2. Do you need one-shot tasks or persistent threads?
3. Do you need approvals and streamed events?
4. Is this automation, rich-client integration, or tool exposure?
5. Select SDK, App Server, plugin, or MCP accordingly.
6. Implement initialize / initialized.
7. Implement thread and turn lifecycle.
8. Handle notifications and approvals.
9. Add timeout, retry, and backpressure behavior.
10. Validate sandbox and permission boundaries before removing the old integration.
## Conclusion
The deprecation of `codex mcp-server` does not mean OpenAI is moving away from MCP.
It means the Codex architecture is becoming more explicit:
```text
MCP Server
β provide external tools
Codex App Server
β embed the Codex runtime in a rich client
Codex SDK
β automation and CI
Codex Plugin
β integrate Codex into another agent client
```
If you previously exposed Codex itself as an MCP server, revisit the actual requirement.
Do you need a one-shot Codex capability, or do you need to embed a complete Codex agent runtime?
Those are now intentionally different integration paths.
For more Codex, MCP, AI coding agent, and developer-infrastructure analysis, visit **Zyentor Picks**: https://www.zyentorpicks.com/.