codex-mcp-bridge
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| CODEX_BIN | No | Path to codex used for autostart. | auto-detected |
| CODEX_EXE | No | Override the codex path used by the install scripts. | auto-detected |
| CLAUDE_BRIDGE_CWD | No | The working directory the peer advertises. | the process cwd |
| CODEX_BRIDGE_MODEL | No | Default model for threads and turns the bridge creates, e.g. gpt-5.6-luna. | from ~/.codex/config.toml |
| CODEX_BRIDGE_REMAP | No | 0 disables cwd remapping between a shared drive and a local checkout. | 1 |
| CODEX_BRIDGE_EFFORT | No | Default reasoning effort: minimal · low · medium · high · xhigh · ultra. | from ~/.codex/config.toml |
| CODEX_APP_SERVER_URL | No | Shared loopback-only app-server endpoint. Non-loopback endpoints are rejeckted because the bridge does not implement remote WebSocket authentication. | ws://127.0.0.1:8791 |
| CODEX_BRIDGE_SANDBOX | No | Sandbox applied to threads created by the bridge: read-only or workspace-write; unrestricted danger-full-access is rejected. | workspace-write |
| CLAUDE_DESKTOP_CONFIG | No | Override the config path used by install-claude-deskstop.mjs. | auto-detected |
| CODEX_BRIDGE_APPROVAL | No | How to answer approval requests from Codex. approve is ignored unless CODEX_BRIDGE_AUTO_APPROVE_ACK=1 is also set. | deny |
| CODEX_BRIDGE_PATH_MAP | No | Optional JSON object mapping absolute source paths to absolute target paths; use it when the same project has a known different path on another machine. | |
| CODEX_BRIDGE_AUTOSTART | No | 0 = never spawn an app-server; one must already be running. | 1 |
| CLAUDE_BRIDGE_PEER_NAME | No | The name Claude shows for this bridge in its agent list. | codex-<pid> |
| CODEX_BRIDGE_OPEN_IN_APP | No | Open delegated or sent threads through the codex://threads/<id> desktop link. | 1 on Windows, 0 elsewhere |
| CODEX_BRIDGE_ALLOWED_ROOTS | No | Absolute project directories permitted for cwd, separated by : (; on Windows); * means every usable workspace. | * in the v1.11.2 installer |
| CODEX_BRIDGE_THREAD_POLICY | No | What authorizes a thread: owned (created by this bridge, or listed in CODEX_BRIDGE_ALLOWED_THREADS) or roots (working inside CODEX_BRIDGE_ALLOWED_ROOTS). Existing config values are preserved on upgrade. | owned in the direct server; installer writes roots for new v1.11.2 entries |
| CODEX_BRIDGE_ALLOWED_THREADS | No | Exact comma-separated thread IDs permitted for read/send/interrupt/open/list; * explicitely permits every thread ID. Under roots, the workspace check still runs. | |
| CODEX_BRIDGE_APPROVAL_POLICY | No | Policy applied to threads created by the bridge. It is no longer caller-controlled. | on-request |
| CODEX_BRIDGE_WORKSPACE_ROOTS | No | Where to look for a project by name, most preferred first, separated by : (; on Windows). Setting it replaces the derived roots rather than adding to them. | $HOME and the bridge's parent directory |
| CODEX_BRIDGE_AUTO_APPROVE_ACK | No | Explicit acknowledgement required to enable automatic command/file approval; set to 1 only after reviewing the risk. | |
| CODEX_BRIDGE_RELEASE_AFTER_TURN | No | Stop the shared bridge app-server after a terminal turn so Codex Desktop can write the handed-off thread. | 1 on Windows, 0 elsewhere |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| delegate_to_codexA | Create a named Codex session at the requested project directory, send Claude's prompt into it, return Codex's reply, and hand the session to Codex Desktop without leaving the bridge writer lock behind. Use for independent new work when the user explicitly or through standing instructions authorizes new conversations. In Desktop mode, supply a fresh requestId per independent task and keep it on retries; omit requestId in legacy app-server mode. Use send_to_codex_thread for unfinished work. |
| send_to_codex_threadA | Send a prompt as a new user turn inside an existing Codex thread and wait for Codex to answer. Use only for the same unfinished task, including follow-up fixes, clarifications, or results; independent new work belongs in a new conversation when authorized. The thread keeps its full history, cwd and model. Use list_codex_threads first if you do not know the threadId. Desktop-owned tasks must use Desktop native delivery; an open task is a valid destination. If legacy delivery reports an active writer, inspect codex_bridge_status and repair the native relay/configuration. Do not close the task, create a replacement, or ask the user to copy the message manually. |
| list_codex_threadsA | List recent Codex threads (id, title, cwd, last update, status) so you can pick the exact threadId to talk to. |
| start_codex_threadA | Start a new Codex task when the user explicitly or through standing instructions authorizes a new conversation for independent work. In Desktop mode include the initial prompt and a fresh requestId to create and assign a visible task atomically; keep requestId unchanged on retries. Continue unfinished work with send_to_codex_thread and its original threadId. Use delegate_to_codex to also wait for its reply. |
| read_codex_threadA | Read a Codex thread without sending anything. In Desktop mode, pass the exact turnId returned by send_to_codex_thread for authoritative assistant item IDs, text, and reply hash; without turnId the native recent-history view may omit items. |
| interrupt_codex_turnA | Stop a turn that is still running in a Codex thread. |
| open_codex_threadA | Bring a Codex thread to the front on Windows or macOS using (codex://threads/) so a human can watch the work live instead of reading the transcript afterwards. |
| stop_codex_app_serverA | Stop the shared app-server this bridge talks to. Use it when work is handed off and the Codex desktop app is open: two app-servers on the same ~/.codex state make the app stutter. The bridge starts a new one automatically the next time it needs it. |
| codex_bridge_statusA | Report how this bridge is wired on the current machine: platform, resolved codex binary, app-server endpoint and whether it is live, plus desktop deep-link support and macOS integrations. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 9 tools
delegate_to_codex, start_codex_thread, and send_to_codex_thread heavily overlap—delegate_to_codex is essentially a superset (create + send + wait), and the new-conversation vs unfinished-work distinction is explained only via lengthy prose that an agent can easily miss. list_codex_threads, read_codex_thread, open_codex_thread, and interrupt_codex_turn are more clearly distinct, but the core conversation-starting trio remains fuzzy.
Most tools follow a consistent verb_codex_noun pattern (list_codex_threads, send_to_codex_thread, read_codex_thread, stop_codex_app_server). The main deviation is codex_bridge_status, which flips to a noun-first form, though it is still readable and clearly its own concept.
Nine tools is well-scoped for a bridge that manages Codex sessions, covering session lifecycle, delivery, monitoring, and status. Slightly heavy given the operational overlap among the send/delegate/start trio, but each tool maps to a real capability.
The surface covers create (start/delegate), list, read, send, interrupt, open, and status—effectively the full session lifecycle an agent needs. The only notable gap is an explicit thread close/delete operation, but the descriptions imply tasks are intentionally never closed, so this is minor.