claude-codex-mcp-bridge
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| CODEX_BIN | No | Path to the Codex CLI executable. Used when Codex is not available as 'codex' on PATH. | |
| BRIDGE_DB_PATH | No | Absolute path to the SQLite database file. Overrides the default location (~/.local/share/claude-codex-bridge/bridge.sqlite). All MCP processes must point to the same database. |
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 |
|---|---|
| bridge_registerA | Register a unique agent name for this conversation. wake: "auto" binds this exact app session for background pings; an explicit {app, sessionId} binds another session; null disables pings; omitted keeps the current binding. Registering again reactivates a retired agent. |
| bridge_sendA | Save a message, then ping its bound recipient in the background. The recipient must be registered (use allowUnregistered only when it will register later). The result carries warnings when the recipient is unlikely to pick the message up. Broadcasts and wake:false sends do not ping anyone. |
| bridge_sessionsA | Read live Claude session IDs and this conversation's own session when the host exposes it. Does not wake anything or read conversation content. |
| bridge_wake_statusB | Read up to 100 recent wake receipts with a per-state summary. Accepted means the app accepted a ping, not that the work is complete. Held/refused respect app permission checks; unknown outcomes are never replayed automatically. |
| bridge_inboxA | List messages addressed to an agent, oldest first, in pages that fit the host's output limit. Acknowledged messages are hidden by default. When hasMore is true, acknowledge handled messages and read again, or pass afterId. |
| bridge_waitA | Keep this agent turn alive until a matching bridge message arrives, for agents without background pings. It cannot wake a chat whose turn has already ended, so call it before going idle. After handling and replying, call bridge_wait again while the coordination thread is active. |
| bridge_ackB | Mark messages as handled for an agent so they drop out of the unread inbox. History is kept. |
| bridge_threadA | Read one page of a conversation thread. Without a cursor it returns the most recent messages; pass beforeId (olderBeforeId) to page back or afterId (newerAfterId) to page forward. |
| bridge_agentsA | List registered agents with unread counts, last activity, ping binding and recent ping health. Retired agents are hidden unless requested. |
| bridge_outboxA | List direct messages an agent sent that the recipient has not acknowledged yet (newest first), with ping outcome and whether the recipient is active, retired or unknown. |
| bridge_retireA | Retire an agent whose task is over: its pings stop, its unhandled messages are closed with a recorded reason (history is kept), and recently active senders get one notice listing what was closed. Registering the name again reactivates it. |
| ask_codexA | Send one bounded implementation, investigation, or verification task to a saved Codex worker in an isolated worktree. This is the simple everyday entry point; no mailbox or thread management is required. |
| review_with_codexA | Ask Codex for a read-only repository review with evidence and actionable findings. Codex runs in a read-only sandbox and the bridge reports whether the workspace changed. |
| bridge_orchestrate_codexA | Start a saved Codex worker in an isolated git worktree (network off) and wait up to waitSeconds for its structured result. If status is waiting_for_fable, answer the question and call bridge_continue_codex. If it is running_codex, the result arrives in the coordinator's mailbox. Independent calls create separate runs. This tool never grants permission to commit, push, deploy, publish, send externally, change credentials, delete data, or mutate production. |
| bridge_continue_codexA | Resume the exact saved Codex session and worktree after Codex asked for a decision (status waiting_for_fable). The sandbox from the first turn is kept. Continue until completed, blocked, failed, or the round limit is reached. |
| bridge_orchestration_waitA | Wait up to timeoutSeconds for a running Codex run to finish its current round, then return its result. Works for runs started by any bridge process. |
| bridge_orchestration_statusA | Recover durable run state and its audit events after a restart or when checking progress. |
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 17 tools
Most tools target distinct resources or lifecycle stages: messaging, agent registration, wake receipts, and Codex orchestration are clearly separated. The main ambiguity is between ask_codex and bridge_orchestrate_codex, both of which start a saved Codex worker in a worktree; descriptions try to distinguish simple use from orchestration, but an agent could still misselect.
The set is predominantly snake_case with a bridge_ prefix, which is predictable for the coordination tools. Two Codex-facing tools (ask_codex, review_with_codex) omit the bridge_ prefix, and bridge_orchestrate_codex versus bridge_orchestration_status/wait uses slightly different forms, but the pattern is still largely readable.
At 17 tools, the server is slightly above the typical 3-15 range, but the count is justified by two subdomains: agent messaging/coordination and Codex task orchestration. Each tool appears to cover a distinct operation rather than duplicating another, so it does not feel bloated.
The surface covers the core lifecycle: agent registration/retirement, sending and reading messages, acknowledgement, threading, wake status, session inspection, and Codex task/review/orchestration flow. Minor gaps remain, such as an explicit cancel/stop for a running Codex run or a way to list active runs directly, but agents can work around these.