Codex Web Bridge

Use ChatGPT Web as the planning UI while this local MCP bridge provides tools for files, code search, shell commands, tests, git status/diff, and lightweight task/process state.

The recommended public setup is:

ChatGPT Web
  -> your HTTPS domain
  -> server reverse proxy
  -> SSH reverse tunnel
  -> local bridge on 127.0.0.1:3838
  -> local projects

This avoids ngrok and does not require exposing your Mac directly to the internet.

What It Provides

• MCP over stdio for local MCP clients.
• MCP over Streamable HTTP for ChatGPT Apps / Connectors.
• Local project tools: read, search, list, write, patch, move, delete.
• Shell/test/git tools with policy checks.
• Workspace/task/process helpers for longer work.
• Optional HTTP token auth for /mcp.
• Audit logs for write/destructive operations.

Quick Start

npm install
npm run build
bash scripts/test-mcp.sh

Run locally:

CODEX_WEB_AUTH_TOKEN="$(openssl rand -hex 32)" node dist/index.js --http 3838
curl -sS http://127.0.0.1:3838/health

Local macOS Service

Generate local-only config files:

bash scripts/configure-local.sh bridge

Install the bridge as a user LaunchAgent:

bash scripts/install-launchd.sh

Stop it:

bash scripts/stop-launchd.sh

Generated files such as launchd/com.codexweb.bridge.plist, launchd/com.codexweb.tunnel.plist, and bridge.policy.json are intentionally ignored by git. Do not commit them; they contain local paths and, usually, a token.

Server Setup Without ngrok

You need:

• A Linux server reachable over SSH.
• A domain with HTTPS terminating on that server.
• A reverse proxy such as nginx.
• SSH key access from your Mac to the server.

1. Start The Local Bridge

bash scripts/install-launchd.sh
curl -sS http://127.0.0.1:3838/health

2. Create An SSH Reverse Tunnel

For an interactive test:

SSH_TARGET="ubuntu@example.com" \
REMOTE_PORT=3839 \
LOCAL_PORT=3838 \
bash scripts/start-ssh-tunnel.sh

With a key:

SSH_TARGET="ubuntu@example.com" \
SSH_KEY="$HOME/.ssh/id_ed25519" \
REMOTE_PORT=3839 \
LOCAL_PORT=3838 \
bash scripts/start-ssh-tunnel.sh

For a macOS LaunchAgent:

SSH_TARGET="ubuntu@example.com" \
SSH_KEY="$HOME/.ssh/id_ed25519" \
REMOTE_PORT=3839 \
LOCAL_PORT=3838 \
bash scripts/configure-local.sh tunnel

bash scripts/install-launchd.sh

On the server, this should respond:

curl -sS http://127.0.0.1:3839/health

3. Reverse Proxy With A Secret Path

ChatGPT's app setup may not give you a place to add a custom bearer header. A practical pattern is:

• Keep CODEX_WEB_AUTH_TOKEN enabled on the local bridge.
• Use a long random path on your HTTPS domain.
• Have nginx inject the bearer token when proxying to the tunnel.

Example nginx location:

location /codex-mcp/<long-random-secret>/ {
    proxy_pass http://127.0.0.1:3839/;
    proxy_http_version 1.1;
    proxy_set_header Authorization "Bearer <your-local-bridge-token>";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    proxy_read_timeout 600s;
    proxy_send_timeout 600s;
}

Then test:

curl -sS https://your-domain.example/codex-mcp/<long-random-secret>/health

The MCP URL for ChatGPT is:

https://your-domain.example/codex-mcp/<long-random-secret>/mcp

In ChatGPT, choose No Auth for the app authentication if nginx is injecting the bearer token.

ChatGPT App Setup

1. Open ChatGPT Web.
2. Go to Apps -> Manage -> Create app.
3. Use Server URL.
4. MCP Server URL:

https://your-domain.example/codex-mcp/<long-random-secret>/mcp

5. Authentication: No Auth if your reverse proxy injects the bearer token.
6. Accept the custom MCP server risk notice.
7. Create and connect the app.

Try a read-only prompt first:

Use Local Codex Bridge. Run project.snapshot for /absolute/path/to/my/project and summarize the project type, git status, and scripts.

Stdio Config

For local MCP clients that support stdio:

{
  "mcpServers": {
    "codex-web-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/codex-web/dist/index.js"],
      "env": {
        "CODEX_WEB_DATA_DIR": "~/.codex-web",
        "CODEX_WEB_POLICY_PATH": "/absolute/path/to/codex-web/bridge.policy.json"
      }
    }
  }
}

Policy

bridge.policy.json controls what local paths and shell commands are allowed.

Default template:

{
  "allowedProjectRoots": ["~"],
  "denyGlobs": [
    "**/.env",
    "**/.env.*",
    "**/*.pem",
    "**/*.key",
    "**/*.p12",
    "**/*.pfx",
    "**/.npmrc",
    "**/.netrc",
    "**/.ssh/**",
    "**/id_rsa",
    "**/id_ed25519"
  ],
  "shell": {
    "enabled": true,
    "denyPatterns": [
      "sudo",
      "rm\\s+-rf\\s+/",
      "chmod\\s+-R",
      "chown\\s+-R",
      "security\\s+find-",
      "launchctl\\s+bootout\\s+system"
    ]
  }
}

For safer use, narrow allowedProjectRoots to specific project directories.

Tools

The server exposes these MCP tools:

Tool	Purpose
project.snapshot	Project summary, git status, language/package hints, bounded file tree
project.scripts	Read package scripts
project.index	Higher-level project index
code.read / code.read_range	Read files or line ranges
code.search	Search with ripgrep-compatible output
file.list / file.stat	Inspect files without reading full contents
file.write / file.patch / file.mkdir / file.copy / file.move	Modify files inside policy boundaries
file.delete	Delete files, requires confirm: true
shell.exec	Run a shell command after policy checks
test.detect / test.run	Detect and run tests
git.status / git.diff / git.checkpoint / git.revert	Git inspection and guarded revert
workspace.*	Register and resolve local workspaces
task.*	Persist lightweight task/session notes
process.*	Start/list/stop managed long-running processes
port.check	Check local TCP ports
bridge.status / bridge.health / bridge.logs	Inspect bridge service health and logs
service.restart	Restart fixed local bridge/tunnel services, requires confirm: true

Security Notes

• Do not expose /mcp publicly without auth or a protected reverse proxy path.
• Do not commit generated plist files, tokens, SSH key paths, logs, or real domains if they are private.
• Prefer a long random URL segment even when token injection is enabled.
• Keep CODEX_WEB_AUTH_TOKEN enabled for public HTTP use.
• Keep .env, .ssh, key files, .npmrc, and .netrc denied.
• Use read-only tools first before write/shell tools.
• Treat shell output and logs as potentially sensitive.
• For long-term use, rotate the secret path and token if they are ever pasted into a public place.
• If your Mac is asleep/offline, ChatGPT cannot reach the local bridge through the tunnel.
• macOS LaunchAgents start after user login, not before login.

Restart Behavior

Server reboot:

• nginx/systemd usually comes back automatically.
• The Mac-side SSH LaunchAgent reconnects when the server is reachable.
• No ChatGPT app reconfiguration is needed if the domain and secret path stay the same.

Mac reboot:

• The LaunchAgents start after you log in.
• The tunnel reconnects if SSH credentials still work.

You need to reconfigure only if the domain, secret path, bridge token, SSH target, SSH key, or ChatGPT app is changed or deleted.

Validation

Local:

curl -sS http://127.0.0.1:3838/health

Server:

curl -sS http://127.0.0.1:<remote-port>/health

Public:

curl -sS https://your-domain.example/codex-mcp/<long-random-secret>/health

MCP initialize:

curl -sS https://your-domain.example/codex-mcp/<long-random-secret>/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"verify","version":"1.0"}}}'

Development

npm run typecheck
npm run build
bash scripts/test-mcp.sh