Codex Desktop Bridge

A configurable MCP bridge for bidirectional handoff between any MCP client and Codex Desktop App Server, with durable callbacks and acknowledgements.

The primary journey starts in Codex:

Codex task
  -> create_handoff (stable handoff_id, exact origin thread)
  -> your provider delivers the contract to an external MCP agent
  -> accept_handoff -> report_handoff(working|completed|failed)
  -> bridge calls Codex App Server turn/start on the original task
  -> get_handoff_status -> ack_handoff

The handoff and callback inbox survive bridge restarts. Agent and origin capabilities are scoped to one handoff, and an accepted handoff is bound to one external agent session. The bridge does not claim it can wake a closed ChatGPT, Claude, Grok, Cursor, or other client; the actual provider must deliver the outbound contract.

Provider adapters such as Slack may carry notifications or handoff contracts, but they are optional delivery surfaces, not the local control plane. The canonical task identity, return path, durable inbox, and acknowledgement remain in the App Server + bridge protocol. See the Slack comparison and boundary.

Why this project

Codex App Server already provides the authoritative thread and turn APIs. This project keeps those low-level operations available, then adds the missing application-level handshake: durable handoff state, session isolation, idempotent event delivery, callbacks, and acknowledgement.

It is not a terminal scraper, a transcript parser, a private Desktop IPC client, or a general workflow scheduler. It launches the documented codex app-server --stdio interface and uses thread/list, thread/read, thread/start, thread/resume, thread/fork, and turn/start.

Related MCP server: handoff-mcp-server

Requirements

• macOS

• Node.js 22.13 or newer

• An installed, authenticated OpenAI Codex binary whose codex app-server --stdio interface is usable

App Server is a versioned product interface that continues to evolve. The bridge probes the installed Codex version at runtime and returns clear protocol failures instead of promising compatibility with every future release.

Install

npm install -g codex-desktop-bridge
codex-desktop-bridge --version

From a source checkout:

npm install
npm test
npm install -g .

Standard MCP client configuration

For stdio clients such as ChatGPT-compatible local runtimes, Claude, Grok integrations, Cursor, and other MCP hosts:

{
  "mcpServers": {
    "codex-desktop-bridge": {
      "command": "codex-desktop-bridge",
      "args": ["stdio", "--config", "/absolute/path/to/config.json"]
    }
  }
}

For direct Streamable HTTP:

codex-desktop-bridge http --config /absolute/path/to/config.json

The default HTTP listener is loopback-only at http://127.0.0.1:8392/mcp. A non-loopback listener is rejected unless bearer authentication is configured. See examples/config.example.json and docs/client-configuration.md.

Handoff tools

• create_handoff: bind an outbound contract to one existing Codex task and return one-time agent/origin capabilities.

• accept_handoff: bind the agent capability to one external session.

• read_handoff: read the exact accepted contract and its event history.

• report_handoff: durably record working, completed, or failed, then inject the update into the original Codex task.

• get_handoff_status: let the origin retrieve durable state.

• ack_handoff: acknowledge a terminal handoff.

The state machine is dispatched -> accepted -> working -> completed|failed -> acknowledged. A unique event_id makes retries idempotent.

Low-level tools

The bridge also exposes list_codex_tasks, read_codex_task, create_codex_task, resume_codex_task, send_to_codex_task, fork_codex_task, report_callback, report_to_chatgpt, list_callbacks, read_callback, and ack_callback.

Read does not resume a task. Resume/send/fork are explicit mutations and require an exact repo/worktree contract. A callback belongs to one explicit client session.

Transports and configuration

The same package supports standard MCP stdio and direct Streamable HTTP. Configuration covers the Codex binary, optional CODEX_HOME, state database, request/task timeouts, HTTP host/port/path/auth/public URL, allowed origins, and log level. Secret bearer values come from a referenced file or environment variable and are never included in bridge_info.

See docs/protocol.md for isolation and restart semantics.

Related projects and design choice

Before the first release, the project compared existing App Server bridges and chose an independent implementation. The low-level protocol comes directly from OpenAI's App Server documentation; no third-party source code was copied. docs/related-projects.md records the bounded comparison and licenses. This project does not claim to be the first Codex bridge.

License

Apache-2.0. See LICENSE.