kkarsyline/codex-app-server-gateway-guide

This page was translated automatically. Technical details may differ from the original. View the original

40 stars 0 forks Quality 68 Trend 20MIT

Practical tutorial on integrating Codex App Server into existing chat frontends and gateways, covering streaming events, thread lifecycles, refills, multi-backend routing, and MCP tool synchronization.

Overview

Document status: 2026-08-22. This article focuses on Codex; There are many related tutorials on the API and Claude Code -p network, but this only discusses compatibility boundaries. This article uses codex in the mode value of the gateway, corresponding to the official Codex App Server integration. claude-p retains its original name because it corresponds to the actual claude -p execution pattern. This solution is suitable for those who already have chat frontends, SSE gateways, session databases, and custom tool systems. The final result is: the same frontend can choose among three backends: API, Claude Code -p, and Codex App Server by conversation; All three backends share message storage, attachments, streaming UI, and utility bubbles; Each provider's session semantics, prompt carriers, and native events remain within their respective adapters. 1. The gateway handles product semantics: conversation, message tree, attachments, persistence, unified SSE, and background tasks. 2. Provider adapter handles protocol semantics: startup, authentication, session/thread, utility events, errors, and interrupts. 3. Tool registration has a single authentic source, then configuring CC and Codex rendering separately; Do not maintain two manual lists. 4. Persona, style, memory retrieval, and refill each have independent responsibilities; Mixing into a huge system prompt can cause updates, caching, and session recovery to all go out of control. This article defines refill as "the necessary historical context for Codex threads after a new creation, restoration, fork, or compact." The gateway extracts historical message summaries, recent complete dialogues, and necessary states from its message database on a budget, forming a temporary context block to place in the next turn/start. Refill only fills the missing parts of the current thread, does not duplicate the entire transcript, and does not replace Codex's native thread history. OpenAI positions App Server as a rich client-side integration interface, covering authentication, conversation history, approvals, and streamed agent events. Automation or CI is better suited for SDKs. Official App Server documentation We choose an App Server process that runs long-term to serve multiple logical conversations.

Overview (machine translated)

Document status: 2026-08-22. This article focuses on Codex; API and Claude Code -p There are many related tutorials on the network, but this only covers compatibility boundaries.

In this article, codex is used in the gateway’s mode value, corresponding to the official Codex App Server integration. claude-p retains its original name because it corresponds to the real claude -p execution pattern.

This solution is suitable for those who already have chat frontends, SSE gateways, session databases, and custom tool systems. The final result is: the same frontend can be selected by conversation among three backends: API, Claude Code -p, and Codex App Server; All three backends share message storage, attachments, streaming UI, and utility bubbles; Each provider’s session semantics, prompt vectors, and native events remain within their respective adapters.

1. Final architecture

There are four most important boundaries:

The gateway is responsible for product semantics: conversation, message tree, attachments, persistence, unified SSE, and background tasks.
Provider Adapter is responsible for protocol semantics: startup, authentication, session/thread, utility events, errors, and interrupts.
Tool registration should have a single true source, then configure CC and Codex rendering separately; Do not maintain two manual lists.
Persona, style, memory retrieval, and refill each have independent responsibilities; Mixing up a huge system prompt can cause updates, caching, and session recovery to spiral out of control.

This article defines refill as “the necessary historical context for Codex threads after a new creation, restoration, fork, or compact.” The gateway extracts historical message summaries, recent complete dialogues, and necessary states from its message database on a budget, forming a temporary context block to place in the next turn/start. Refill only fills in the missing parts of the current thread, does not duplicate the entire transcript, and does not replace Codex’s native thread history.

2. Why choose App Server?

Codex has three common types of access surfaces:

Access Interface	Suitable Scenarios	Limitations in the Long Chat Front-End
`codex exec --json`	CI, scripting, one-time automation	High costs for managing processes and history per round, limited deep interaction capabilities
Codex SDK	In-app programming calls, wanting to use type encapsulation	Very suitable; You still need to define gateway events and persistent contracts yourself
`codex app-server`	Custom rich client, complete thread/turn/event/approval integration	Protocol is broad, requires rigorous adapter and version testing

This page was translated automatically. Technical details may differ from the original.

Install

This server does not publish a one-line install command.

Open the repository installation guide New to MCP? Start with the mcpskill.org guide →

Configuration

{
  "mcpServers": {
    "memory": {
      "type": "http",
      "url": "http://memory.example:8000/mcp"
    }
  }
}