The Codex App Server is a bidirectional JSON-RPC protocol that decouples the Codex coding agent from client surfaces (CLI, IDE, Web). It introduces three conversation primitives (Item, Turn, Thread) to manage state and rejects the Model Context Protocol (MCP) in favor of richer session semantics required for IDE interactions like streaming diffs.
Knowledge Base
📝 Context Summary
The Codex App Server is a bidirectional JSON-RPC protocol that decouples the Codex coding agent from client surfaces (CLI, IDE, Web). It introduces three conversation primitives (Item, Turn, Thread) to manage state and rejects the Model Context Protocol (MCP) in favor of richer session semantics required for IDE interactions like streaming diffs.
OpenAI Codex App Server Architecture
1. Architecture Overview
The Codex App Server is a bidirectional protocol designed to decouple the Codex coding agent’s core logic from its various client surfaces (CLI, VS Code, Web, Xcode). It solves the “N-to-1” problem of agent integration by exposing a single, stable API that powers all experiences.
Unlike simple request/response models, the App Server manages complex, stateful agent interactions where a single user request unfolds into a structured sequence of actions, artifacts, and incremental progress updates.
2. Conversation Primitives
To model agentic workflows faithfully, the architecture defines three core primitives:
| Primitive | Definition | Lifecycle |
|---|---|---|
| Item | The atomic unit of input or output (User message, Agent message, Tool execution, Diff). | started → delta (streaming) → completed |
| Turn | A grouped sequence of Items produced by a single unit of agent work, initiated by user input. | Initiated by User → Concluded by Agent |
| Thread | The durable container for an ongoing session. Supports creation, resumption, forking, and archival. | Persisted event history for reconnection. |
3. Protocol Mechanics
The system uses JSON-RPC streamed as JSONL (JSON Lines) over stdio.
3.1 Server-Initiated Requests (Approval Flows)
A key differentiator of this protocol is support for server-initiated requests.
* Scenario: The agent needs permission to execute a destructive command.
* Flow: The server sends a request to the client → The Turn pauses → The Client responds with allow or deny → The Turn resumes.
4. Comparison with Model Context Protocol (MCP)
OpenAI explicitly evaluated and rejected the Model Context Protocol (MCP) for the Codex App Server.
- The Limitation: MCP’s tool-oriented model could not cleanly map the rich session semantics required for a coding IDE.
- Specific Gaps: MCP struggled to handle streaming diffs, complex approval flows, and thread persistence in a way that felt native to VS Code.
- Coexistence: OpenAI still supports MCP for simpler, tool-based workflows but recommends the App Server for full-fidelity agent integrations.
5. Deployment Patterns
Clients embed the App Server using three primary patterns:
- Local Child Process: (VS Code, Desktop App) The client bundles a platform-specific binary and communicates via bidirectional
stdio. - Decoupled Binary: (Xcode) The client points to a separately updated App Server binary, allowing logic updates without client releases.
- Remote Container: (Web Runtime) A worker provisions a container with the App Server; the browser communicates via HTTP/SSE, keeping the UI lightweight while the server manages state.
6. Industry Context: App Server vs. ACP
The App Server exists alongside the Agent Client Protocol (ACP) (supported by Zed and JetBrains).
* Codex App Server: Specific to the Codex harness and OpenAI ecosystem.
* ACP: Aims to be the “Language Server Protocol (LSP)” for agents—a universal standard connecting any agent to any editor.
Sources
- [1]Openai Codex App Server Architecture
- Codex App Server
- Bidirectional JSON-RPC
- Conversation Primitives (Item, Turn, Thread)
- Agent Client Protocol (ACP)
Table of Contents
Knowledge
How To
Trending
- Codex App Server
- Bidirectional JSON-RPC
- Conversation Primitives (Item, Turn, Thread)
- Agent Client Protocol (ACP)