App server vs MCP vs ACP vs SDK
Four Codex integration surfaces that get confused constantly. The one-line rule that separates them, and how to pick without reading four sets of docs.
Four things in the Codex ecosystem speak JSON-RPC and get mixed up constantly. Here is the rule that sorts most of it:
The four surfaces#
| Surface | Direction | Use it when |
|---|---|---|
| App server | Your client → Codex | Building a GUI, editor extension, IDE panel |
| SDK | Your script → Codex | Automating a task, CI, orchestration |
| MCP | External tool → Codex | Giving Codex access to a database, API, service |
| ACP | Editor ↔ any agent | Supporting many agents, not just Codex |
App server vs MCP#
The genuinely confusing pair, because Codex can be both — it can run as an MCP server, and it has an app-server that manages MCP servers.
MCP is tool-oriented. You write an MCP server that exposes a database, an internal API, a search index, and Codex calls it as a tool. The app-server even has methods for this — mcpServer/tool/call, mcpServerStatus/list — because managing your MCP servers is one of its jobs.
The app-server is session-oriented. It exposes threads, turns, streaming deltas, approval flows and persistent history — everything a client needs to be a Codex interface.
Why MCP wasn't enough#
This is documented history rather than speculation, and it's the clearest explanation of why the app-server exists at all.
When OpenAI built the VS Code extension, they first tried exposing Codex as an MCP server. It didn't work well. The session semantics an IDE needs — streaming diffs, approval flows, thread persistence — don't map cleanly onto MCP's tool-oriented model. Maintaining MCP semantics in a way that made sense for VS Code proved difficult, so the app-server was built instead.
OpenAI still supports running Codex as an MCP server for simpler workflows, but recommends the app server for full-fidelity integrations.
So the practical rule:
- Want Codex to use your thing? MCP.
- Want your thing to drive Codex, with streaming and approvals? App server.
- Just want to fire a prompt and read the result? SDK — simpler than both.
App server vs SDK#
Same underlying agent, different altitude.
| App server | SDK | |
|---|---|---|
| Level | Raw JSON-RPC protocol | Typed, language-idiomatic wrapper |
| You manage | Process, handshake, framing, events | Very little |
| Streaming deltas | Yes, every event | Higher-level |
| Approval flow | Full control | Sandbox presets |
| Best for | Interactive clients | Automation, CI |
| Effort | Substantial | An afternoon |
OpenAI's own guidance: "If you are automating jobs or running Codex in CI, use the Codex SDK instead."
Start with the SDK. Most people who think they need the app-server actually want the SDK, and discovering that after building a JSON-RPC client is an expensive way to learn it. Drop down to the app-server only when you hit something the SDK can't express — usually fine-grained approval handling or per-item streaming.
What ACP is, and why it exists#
ACP — the Agent Client Protocol — is a different axis entirely. It's an open protocol, Apache licensed, developed by Zed and JetBrains, that lets an editor talk to any compliant agent.
The relationship to Codex is concrete: Zed's Codex integration uses codex-acp (@zed-industries/codex-acp), an adapter built on the Codex app-server. Codex is live in Zed through it.
Zed / JetBrains ──ACP──► codex-acp adapter ──app-server──► Codex
──ACP──► some other agentThe distinction that matters:
- App server is Codex-specific. One agent, deep integration.
- ACP is agent-agnostic. Many agents, one integration, at the cost of a shallower common denominator.
If you're building an editor and want to support Codex and Claude and whatever ships next, ACP is the leverage. If you're building a Codex client and want everything Codex can do, go straight to the app-server.
This is the same trade-off T3 Code makes at the product level — breadth across four providers versus depth in one.
Decision table#
| You are building | Use |
|---|---|
| A script that runs Codex on a repo | SDK |
| A CI job that fixes failing tests | SDK |
| A GUI with live streaming and approvals | App server |
| An editor extension, Codex only | App server |
| An editor supporting several agents | ACP |
| A tool for Codex to call | MCP |
| A database Codex can query | MCP |
FAQ#
What is the difference between the Codex app server and an MCP server?#
They point in opposite directions. MCP connects external tools to Codex, so Codex can call your database or API. The app server connects clients to Codex, so your GUI or editor can drive it with streaming and approvals.
Can Codex run as an MCP server?#
Yes, and OpenAI still supports it for simpler workflows. But they recommend the app server for full-fidelity integrations, because MCP's tool-oriented model doesn't cleanly express streaming diffs, approval flows and thread persistence.
What is ACP and how does it relate to the Codex app server?#
ACP, the Agent Client Protocol, is an open protocol from Zed and JetBrains for editors to talk to any agent. Zed's Codex support uses a codex-acp adapter built on top of the Codex app-server, so ACP sits above it rather than competing with it.
Should I use the app server or the SDK?#
The SDK unless you have a specific reason not to. It's far less work and covers automation and CI. Move to the app-server when you need per-event streaming or fine-grained approval control that the SDK doesn't expose.
Why did OpenAI build the app server instead of using MCP?#
They tried MCP first for the VS Code extension. The richer session semantics an IDE needs — streaming diffs, approvals, thread persistence — didn't map onto MCP's tool-oriented model, so they built a purpose-built protocol.