codex-mcp-bridge
Provides tools for interacting with OpenAI's Codex CLI, enabling an MCP client to run queries, manage threads, read session history, and optionally allow file modifications and shell commands under explicit approval policies.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@codex-mcp-bridge Ask Codex to review the recent commits for potential security issues."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
codex-mcp-bridge
MCP server that lets an MCP client (Claude Code) drive OpenAI Codex as a sub-agent: many independent or threaded queries, plus actions (shell commands, file edits) when explicitly opted into.
Important: this project does not call the OpenAI HTTP API. It drives the
Codex CLI (the codex executable) locally and/or reads local Codex session
files. Authentication and session state come from the locally-installed
codex CLI (for example, codex login), and the bridge operates against
that local CLI and its session files rather than an external API key or
billing endpoint.
Auth
Uses whatever codex login has already set up on this machine — a ChatGPT
subscription login, not API-key billing. The bridge launches the codex
executable as a child process so it inherits the current environment and the
CLI's local auth state. Do not try to configure apiKey/baseUrl/env
settings here: they are not used and env would replace the child's
environment rather than merging it, which breaks codex PATH resolution and
auth lookup.
Check status any time with:
codex login statusRelated MCP server: agent-fleet
Tool: codex_ask
One tool, parameterized:
prompt(required),working_directory(required, absolute path — no implicit default, so Codex never silently operates on the wrong repo).thread_id— pass back the id returned by a previous call to continue that conversation; omit to start a new one. Threads are persisted by the Codex CLI itself (~/.codex/sessions), so ids remain valid across restarts of this server.sandbox_mode(read-onlydefault /workspace-write/danger-full-access) andapproval_policy(neverdefault /on-request/on-failure/untrusted) — the "actions" knob. Default is read-only with no auto-approval: Codex can inspect the repo and answer, but cannot write files or run arbitrary commands unless a call explicitly asks forworkspace-write. Since this runs non-interactively (codex execunder the hood), there's no one to answer an approval prompt either way — anything outsidesandbox_modeis simply denied.require_git_repo,additional_directories,network_access,web_search,model,reasoning_effort,output_schema(JSON Schema for structured output),timeout_ms.
Independent calls (different or omitted thread_id) run concurrently as
separate Codex conversations — that's what covers "many queries" alongside
a single ongoing thread.
Tool: codex_cloud_tasks
Lists Codex Cloud background tasks, or (with task_id) shows one task's
status. Wraps codex cloud list --json / codex cloud status <id> directly
(not part of the CLI's documented surface) — these are undocumented/
experimental, so the JSON field names in the list output aren't guaranteed
stable across CLI versions. status has no --json form; its output is
passed through as-is.
Tool: codex_local_sessions
Lists recent local Codex CLI sessions — the ones codex resume picks
from — most recently touched first. codex resume itself is an
interactive-only picker with no scriptable output, so this reads
~/.codex/session_index.jsonl directly instead (also undocumented). That
index only carries session id, current thread name, and last-updated time —
no live/idle status or working directory; a session can be renamed multiple
times, so entries are deduped by id, keeping the most recent name.
Note this index only records interactively created sessions. Threads
started programmatically (including by codex_ask) are real and resumable
but do not appear here.
Tool: codex_read_thread
Reads the message history of any thread, interactive or programmatic, by
locating its rollout JSONL under ~/.codex/sessions and parsing it. No API
call, no quota — it works even when the account is rate-limited.
thread_id(required),limit(default 50, counts back from newest),include_reasoning(default false),max_chars(per-message truncation).
Returns the thread's cwd and source from its session_meta header along
with the messages.
Notes on driving a thread you want to watch
A thread created programmatically never enters the interactive session index,
so it won't show up in codex resume's default picker or the desktop app. If
you want to watch the conversation in the normal Codex UI, start the thread
there first, then pass its id to codex_ask.
Two behaviours worth knowing:
The desktop UI does not live-tail a thread, and navigating to it in an existing window serves a cached copy. Open the thread in a new window to see externally injected messages.
A turn that fails (e.g. rate limit) has already appended your message to the rollout. Rollouts are append-only, so a failed call is not a no-op.
Build
npm install
npm run buildRegister with Claude Code (user scope)
claude mcp add codex-bridge --scope user -- node /absolute/path/to/codex-mcp-bridge/dist/index.jsProbe scripts
probe-*.mjs are small standalone experiments used to work out the
behaviours above (app-server wire framing, what codex mcp-server exposes,
why codex-reply can't reach persisted threads, SDK-only resume). They are
not part of the server; each prints its usage when run without arguments.
Available Tools
4 toolscodex_askAsk Codex (OpenAI, ChatGPT subscription)ADestructive
Send a prompt to OpenAI Codex and get its response back. Codex can, if sandbox_mode is set to workspace-write, actually run shell commands and edit files under working_directory — not just answer in text. Pass the thread_id from a prior call to continue that conversation; omit it to start a fresh one. Independent calls (different or omitted thread_id) run concurrently as separate Codex conversations, so this can be used for many parallel queries as well as a single ongoing one.
Inputs: prompt (required), working_directory (required), model, thread_id, +9 more.
codex_cloud_tasksCodex Cloud task statusARead-onlyIdempotent
List Codex Cloud background tasks, or (with task_id) show the status of one. Wraps the undocumented codex cloud list --json / codex cloud status <id> CLI commands — field names in the JSON list output are not guaranteed stable across Codex CLI versions. status has no --json form; its output is returned as-is.
Inputs: limit, cursor, task_id, environment_id.
codex_local_sessionsLocal Codex work sessionsARead-onlyIdempotent
List recent local Codex CLI sessions — the ones codex resume picks from — most recently touched first. Reads the undocumented ~/.codex/session_index.jsonl index directly, since codex resume itself is an interactive-only picker with no scriptable output. Only exposes what that index carries: session id, current thread name, and last-updated time — not live/idle status or working directory.
Inputs: limit.
codex_read_threadRead a Codex thread transcriptARead-onlyIdempotent
Read the message history of any Codex thread — whether it was created interactively (GUI / VS Code / TUI) or programmatically. Reads the thread's rollout JSONL from ~/.codex/sessions directly, so it needs no API call, consumes no quota, and works even when the account is rate-limited. Returns the most recent messages by default.
Inputs: thread_id (required), limit, max_chars, include_reasoning.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: codex_ask sends prompts, codex_cloud_tasks manages cloud background tasks, codex_local_sessions lists local sessions, and codex_read_thread reads message history. There is no overlap in either target resource or action.
All tools share the codex_ prefix, making them easy to group, but the pattern is not perfectly uniform: codex_ask and codex_read_thread use verb_noun, while codex_cloud_tasks and codex_local_sessions are noun-only. Still, the names are clear and predictable enough.
Four tools is well-scoped for a lightweight bridge to Codex. Each tool covers a distinct integration point without being too sparse or bloated.
The set covers the core needs: sending prompts, reading threads, listing sessions, and checking cloud tasks. Minor gaps exist, such as no ability to cancel a cloud task or resume a local session programmatically, but these are not essential for the bridge's apparent purpose.
Maintenance
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
Hosted X (Twitter) MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Related MCP Servers
- AlicenseAqualityFmaintenanceMCP server for running external coding agents as background tasks inside Claude Code. Supports multiple backends including Codex, Grok, GLM, DeepSeek, and more.7MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that enables Claude Code to delegate tasks to Codex for real-time collaborative code generation and execution.MIT
- AlicenseAqualityCmaintenanceAn MCP server for running Claude Code and the Codex CLI as a pair: Claude drives, and hands self-contained tasks to Codex as background jobs.8MIT
- AlicenseAqualityDmaintenanceAn MCP server that lets Claude Code delegate durable background tasks, reasoning profiles, thread resumption, and native image generation to your local Codex CLI.101MIT