codex-gpt-bridge

Small MCP bridge project for both directions between ChatGPT/OpenAI models and local Codex.

Plain meaning:

• ChatGPT -> Codex: ChatGPT can act as the planner, while this local HTTP MCP server forwards only scoped execution requests to the official codex mcp-server running on your machine.
• Codex -> ChatGPT-like model: Codex can call a local stdio MCP server named chatgpt, which forwards explicit prompts to the official OpenAI Responses API.

Important boundary: the Codex -> model direction does not call the ChatGPT web UI or ChatGPT private product backend. It uses the official OpenAI API, so it needs OPENAI_API_KEY and API model access.

Daily ChatGPT -> Codex use

Yes, this is MCP. ChatGPT sees Local Codex Bridge Secure as an app with five MCP tools:

• bridge_status
• codex_read
• codex_run
• codex_reply
• codex_job_status

ChatGPT role: advisor and reviewer

Treat external ChatGPT as the top-level advisor, not as the local executor. Its two best jobs are:

1. Before execution: inspect enough repo context through codex_read, then write the plan, risks, work order, and success checks.
2. After execution: act as an independent critical reviewer. It should read the changed files or diff through codex_read and return PASS or concrete blockers.

Local Codex is still responsible for execution: editing files, running tests, compiling, rendering, inspecting diffs, and committing. Keep ChatGPT tool calls narrow so it can reason well and so the bridge stays stable.

Advisor prompt:

@Local Codex Bridge Secure 调用 codex_read，只传 prompt：你是这个项目的顶层 advisor。只读调查当前 allowed root，先列出和任务相关的 repo facts，然后给出整体方案、执行顺序、风险、验收标准，以及可以交给 Codex 执行的下一步指令；不要修改任何文件。

Reviewer prompt:

@Local Codex Bridge Secure 调用 codex_read，只传 prompt：你是独立 critical reviewer。只读复查当前改动是否满足计划；不要修改、不要编译、不要运行 shell。只输出 status: PASS/NEEDS_CHANGES、blockers、evidence、next_instruction_for_codex。

Best daily path is OpenAI Secure MCP Tunnel. After the one-time setup, keep the local daemon running with the Keychain-backed launcher:

cd /path/to/codex-gpt-bridge
npm run bridge:chatgpt:secure:keychain

Replace /path/to/... examples with your own absolute local paths.

If this is installed as a macOS LaunchAgent, there is no terminal step. Use ChatGPT directly:

@Local Codex Bridge Secure 调用 codex_read，只传 prompt：调查当前 project 顶层有哪些文件和目录，说明每个重要文件的用途；不要修改任何文件。

Prompt templates

Usually you only need the app name and the task. If the bridge has exactly one allowed root, codex_read uses that root automatically and always forces Codex read-only. Use codex_run only when you intentionally start write mode.

Fixed agent flow

Use this flow exactly. Do not guess tool names or pass extra arguments.

1. Confirm the app can reach the bridge:

@Local Codex Bridge Secure 调用 bridge_status。只返回 allowedRoots、defaultCwd、defaultSandbox、allowWorkspaceWrite、allowDangerFullAccess、upstreamTools。

2. For read-only investigation, call codex_read and pass only prompt:

@Local Codex Bridge Secure 调用 codex_read，只传 prompt：<your task>; 不要修改任何文件。

3. If the result contains status=running, copy the exact jobId and query it explicitly:

@Local Codex Bridge Secure 调用 codex_job_status，只传 jobId：<exact jobId>

4. Use codex_reply only after a completed read/run returns a threadId.
5. Use codex_run only for intentional write-mode work, after restarting the bridge with a narrow CODEX_GPT_BRIDGE_ROOT.
6. If ChatGPT says automatic polling was blocked, do not retry the same vague instruction. Paste the exact jobId.
7. If ChatGPT cannot see codex_read, refresh the app in ChatGPT Settings -> Apps -> Local Codex Bridge Secure -> Refresh, then start a new chat.

Status check:

@Local Codex Bridge Secure 调用 bridge_status。只返回 allowedRoots、defaultCwd、defaultSandbox、allowWorkspaceWrite、allowDangerFullAccess、upstreamTools。

Inspect files in a repo:

@Local Codex Bridge Secure 调用 codex_read，只传 prompt：调查当前 allowed root 的顶层文件和目录，说明每个重要文件的用途；不要修改任何文件。如果返回 status=running 和 jobId，继续调用 codex_job_status 直到 completed 或 failed。

If codex_read or codex_run returns status=running, poll the job:

@Local Codex Bridge Secure 调用 codex_job_status：jobId=<job id from codex_read or codex_run>

ChatGPT may block automatic chained polling when it tries to reuse a jobId from the previous tool result by itself. If that happens, paste the exact jobId into the next prompt as shown above; that path is verified.

Continue the same Codex thread after codex_read or codex_run returns a threadId:

@Local Codex Bridge Secure 调用 codex_reply：
threadId=<thread id from previous codex_read or codex_run>
prompt=继续上一轮，只读检查 README.md 和 docs/chatgpt-setup.md 是否解释清楚日常用法；不要修改任何文件。

For a different project, restart the bridge with that repo as the only allowed root:

CODEX_GPT_BRIDGE_ROOT="/absolute/path/to/project" npm run bridge:chatgpt:secure:keychain

For edits, keep the root narrow and start write mode only for the target repo:

CODEX_GPT_BRIDGE_ROOT="/absolute/path/to/project" npm run bridge:chatgpt:secure:write:keychain

Then in ChatGPT:

@Local Codex Bridge Secure 调用 codex_run，只传 prompt：在当前 allowed root 内修改我的简历。先检查相关文件，说明计划，然后执行最小改动并运行可用检查。

For iterative review/edit loops, keep each tool call narrow:

1. codex_read: ask Codex to inspect the file and return a concrete edit plan.
2. codex_run: ask Codex to apply one narrow edit set. Do not ask it to compile, run long shell commands, or do broad cleanup inside the same bridge call.
3. Verify locally from Codex or your terminal: compile, render, run tests, and inspect the diff.
4. codex_read: send the updated file back through ChatGPT for review.
5. Repeat only if ChatGPT returns a real blocker.

Stable edit prompt:

@Local Codex Bridge Secure 调用 codex_run，只传 prompt：只修改当前 allowed root 内的 <file>。按上一轮建议做最小改动；不要编译、不要运行 shell、不要改其他文件。完成后只总结改了什么。

Stable final review prompt:

@Local Codex Bridge Secure 调用 codex_read，只传 prompt：只读复查 <file> 是否已经解决上一轮 blocker；不要修改、不要编译、不要运行 shell。只输出 status: PASS/NEEDS_CHANGES、blockers、notes。

One-time secure setup needs:

security add-generic-password -a "$USER" -s "codex-gpt-bridge:control-plane-api-key" -w "<runtime-api-key>" -U
security add-generic-password -a "$USER" -s "codex-gpt-bridge:control-plane-tunnel-id" -w "tunnel_..." -U

Then configure ChatGPT with Connection = Tunnel, the matching tunnel id, and Authentication = No Auth.

The older Cloudflare quick tunnel path still exists for smoke tests, but it is not the recommended daily workflow because the URL changes and can fail DNS.

Why

Codex already ships a stdio MCP server with two useful tools:

• codex: start a local Codex session.
• codex-reply: continue a Codex session by thread id.

ChatGPT Apps/GPTs need an HTTP-accessible MCP endpoint. This project is the small missing adapter: HTTP MCP in, official Codex MCP out, with local safety policy in the middle.

For the other direction, Codex can already connect to stdio MCP servers. This project adds codex-chatgpt-mcp, a small MCP server exposing one tool, ask_chatgpt, backed by the OpenAI Responses API.

Safety defaults

• Binds to 127.0.0.1 by default.
• Accepts codex_read.cwd and codex_run.cwd only under the configured roots. This is a bridge-level starting-directory gate, not OS-level file isolation.
• Uses Codex read-only sandbox by default.
• Requires either CODEX_GPT_BRIDGE_TOKEN or explicit local-only CODEX_GPT_BRIDGE_NO_AUTH=1.
• Does not expose raw shell, process control, full Codex app-server, or arbitrary Codex config.
• Blocks delegation when sensitive-looking files such as .env, private keys, or .pem files are present under the requested working directory.
• Allows codex_reply only for threads first created through this bridge, and reruns the sensitive-file preflight before continuing them.
• Blocks workspace-write unless CODEX_GPT_BRIDGE_ALLOW_WRITE=1.
• Does not expose danger-full-access as a per-call ChatGPT option.

Install

npm install
npm run build

Codex CLI must be installed and logged in:

codex --version
codex mcp-server --help

Codex -> ChatGPT-like model

Set an OpenAI API key first:

export OPENAI_API_KEY="<openai-api-key>"
export CODEX_CHATGPT_MODEL="gpt-5.5"

This repository includes a project-scoped Codex MCP config at .codex/config.toml:

[mcp_servers.chatgpt]
command = "npm"
args = ["run", "chatgpt:mcp"]
env_vars = ["OPENAI_API_KEY", "OPENAI_BASE_URL", "CODEX_CHATGPT_MODEL", "CODEX_CHATGPT_TIMEOUT_MS"]

After opening a fresh Codex thread for this trusted project, Codex should have a chatgpt MCP server with one tool:

• ask_chatgpt: send an explicit prompt to the configured OpenAI API model and return text. Optional reasoningEffort values for the default gpt-5.5 model are none, low, medium, high, and xhigh.

Manual smoke test without real API access:

npm run build
node dist/chatgpt-cli.js

The server runs over stdio and waits for MCP JSON-RPC messages. The automated test suite verifies tool registration and request shaping without calling the real API.

Prefer the project config above because env_vars forwards OPENAI_API_KEY from the running Codex environment without writing the secret into a config file. If you move this MCP config outside the project, add an absolute cwd that points to this repository before using npm run chatgpt:mcp.

Run locally

From the repo you want ChatGPT to delegate into:

CODEX_GPT_BRIDGE_NO_AUTH=1 \
CODEX_GPT_BRIDGE_ROOTS="$PWD" \
npm run dev

Server:

http://127.0.0.1:8765/mcp

For a non-local bind:

export CODEX_GPT_BRIDGE_TOKEN="$(openssl rand -hex 32)"
CODEX_GPT_BRIDGE_HOST=0.0.0.0 \
CODEX_GPT_BRIDGE_ROOTS="/Users/me/project" \
npm run start

Use Authorization: Bearer <token> from your MCP client.

When exposing a localhost server through an HTTPS tunnel, keep the bridge bound to 127.0.0.1 and explicitly allow the tunnel host so the MCP SDK DNS-rebinding protection accepts the forwarded Host header:

CODEX_GPT_BRIDGE_ALLOWED_HOSTS=127.0.0.1,localhost,your-tunnel.example.com \
CODEX_GPT_BRIDGE_NO_AUTH=1 \
CODEX_GPT_BRIDGE_ROOTS="/Users/me/project" \
npm run start

Use no-auth only for short-lived localhost/tunnel smoke tests. For durable use, put OAuth or a trusted auth proxy in front of the bridge.

ChatGPT connection

For ChatGPT Apps/GPTs, expose the local MCP endpoint with one of:

• OpenAI Secure MCP Tunnel.
• Cloudflare Tunnel.
• ngrok.

Then configure the ChatGPT app/connector MCP URL to the HTTPS /mcp endpoint. Keep the bridge bound to local host where possible and put the tunnel on top.

Built-in bearer-token auth is intended for local development, manual MCP clients, or a trusted proxy. Production ChatGPT Apps that require protected-tool auth should put an OAuth 2.1 / PKCE layer in front of this bridge; OAuth is not implemented in v0.1.

Observed ChatGPT Developer Mode flow:

1. Open ChatGPT Settings -> Apps -> Create app.
2. Use Server URL.
3. Set MCP Server URL to the tunnel HTTPS /mcp endpoint.
4. Set Authentication to No Auth for local smoke tests.
5. Accept the custom MCP server risk warning and create/connect the app.
6. In a chat, mention the app and ask it to call bridge_status, codex_read, codex_run, codex_reply, or codex_job_status.

Tools exposed to ChatGPT

bridge_status

Reports bridge policy, allowed roots, and upstream Codex MCP tool availability.

codex_read

Starts a read-only Codex inspection in an allowed working directory. This is the default daily tool for repo investigation and planning context.

It accepts the same prompt, optional cwd, and optional timeoutMs fields as codex_run, but it does not accept a sandbox option. The bridge always forwards sandbox=read-only.

Long reads use the same status=running + jobId flow as codex_run.

codex_run

Starts a Codex session in an allowed working directory. Use this for write-mode workflows; prefer codex_read for read-only investigation.

If Codex finishes quickly, the tool returns the Codex result directly. If Codex runs longer than CODEX_GPT_BRIDGE_FAST_RETURN_MS, which defaults to 25 seconds, the tool returns:

{
  "status": "running",
  "jobId": "..."
}

Call codex_job_status with that jobId until the job is completed or failed.

Required:

• prompt

Optional:

• cwd: defaults to the only configured allowed root; required when multiple roots are configured.
• sandbox: read-only by default; workspace-write appears only when the bridge owner starts write mode.
• timeoutMs

Approval policy is owner-controlled through CODEX_GPT_BRIDGE_APPROVAL_POLICY; callers cannot lower it per request.

Sensitive file preflight:

codex_read and codex_run refuse to start if they find common secret files under cwd, including .env, .npmrc, .netrc, private SSH key names, .pem, .key, .p12, and .pfx files. Disable only for a deliberately sanitized environment:

CODEX_GPT_BRIDGE_DISABLE_SECRET_SCAN=1 codex-gpt-bridge

codex_reply

Continues a Codex session that was first created through this bridge.

Required:

• threadId
• prompt

The bridge rejects unknown thread ids and reruns the sensitive-file preflight against the original session directory before forwarding the reply.

Long replies use the same status=running + jobId flow as codex_run.

codex_job_status

Checks a long-running codex_read, codex_run, or codex_reply job.

Required:

• jobId

Tracked sessions are in memory only, capped at 1000 entries, and expire after 6 hours. Restarting the bridge clears them.

Development

npm run check

The tests use a fake upstream and do not call the real model.

Existing project comparison

riccilnl/colameta is highly related and much broader: ChatGPT/GPTs to local executors, plan management, preview/apply, reports, and Git closure. It is alpha and its license text forbids commercial use, so this project does not copy its code.

tuannvm/codex-mcp-server is a mature Claude-to-Codex wrapper. It is useful prior art, but this project targets ChatGPT HTTP MCP and safety policy around the official Codex MCP server.