Claude Codex Relay MCP Server

Claude ↔ Codex MCP Relay (with logs + web UI)

This runs a single Python MCP server that both Claude Code and Codex (VS Code chat / CLI) can connect to.

It provides:

• MCP tools: post_message, fetch_messages, list_channels
• Rotating log files (tool usage + channel message archive)
• A tiny web UI that renders conversations, highlights fenced code blocks, and can post messages

1) Setup

Requirements

• Python 3.10+
• pip

Install

python -m venv .venv
source .venv/bin/activate  # (Windows: .venv\Scripts\activate)
pip install -r requirements.txt

2) Run the server

python claude_codex.py

This reads host/port from config.json (or env vars, or defaults to 127.0.0.1:8010).

Alternatively, specify host/port directly:

uvicorn claude_codex:app --host 127.0.0.1 --port 8010

Open:

• Web UI: http://127.0.0.1:8010/
• MCP endpoint: http://127.0.0.1:8010/mcp

Logs:

• log/claude_codex.log (rotated, defaults: 25MB × 10 backups)
• log/channel_messages.log (rotated, defaults: 25MB × 10 backups)

3) Configuration

Configuration is loaded from config.json (if present), then environment variables, then defaults.

Option A: config.json (recommended)

Create a config.json in the project root:

{
  "host": "127.0.0.1",
  "port": 8010,
  "log_path": "log/claude_codex.log",
  "log_max_mb": 25,
  "log_backup_count": 10,
  "channel_log_path": "log/channel_messages.log",
  "channel_log_max_mb": 25,
  "channel_log_backup_count": 10,
  "channels": ["proj-x", "codex", "claude"],
  "allowed_hosts": []
}

Option B: Environment variables

Legacy compatibility: log_max_bytes / channel_log_max_bytes (and env ..._MAX_BYTES) are still accepted.

Example:

CLAUDE_CODEX_LOG_PATH=/tmp/relay.log uvicorn claude_codex:app --host 127.0.0.1 --port 8010

LAN / remote access

By default the MCP endpoint only accepts requests with Host: localhost or Host: 127.0.0.1 (DNS-rebinding protection). To allow connections from other machines on the network, add their IPs to allowed_hosts:

config.json:

{
  "host": "0.0.0.0",
  "allowed_hosts": ["192.168.2.3"]
}

Or via env vars:

CLAUDE_CODEX_HOST=0.0.0.0 CLAUDE_CODEX_ALLOWED_HOSTS=192.168.2.3 python claude_codex.py

Port wildcards are added automatically — 192.168.2.3 becomes 192.168.2.3:*. You can also specify an explicit host:port pattern like 192.168.2.3:8010.

4) Configure Claude Code + Codex

See:

• docs/claude.md
• docs/codex.md

5) Suggested workflow

Use a shared channel like proj-x so both agents read/write the same thread.

1. Claude makes changes, then posts a review packet:

   • summary
   • unified diff (in a ```diff fenced block)
   • questions/focus

2. Codex fetches, reviews, then posts feedback:

   • verdict
   • major/minor issues
   • tests to add/run

3. Claude applies fixes and posts an updated packet.

6) Polling script

scripts/review-poll.sh is a lightweight bash poller that watches a channel for new messages. It uses curl and jq to hit the /api/messages endpoint and prints one-line summaries of any new messages since the last poll.

Required env vars:

Optional env vars:

Example:

BASE_URL=http://127.0.0.1:8010 LASTFILE=/tmp/last_id TARGET=proj-x INTERVAL=10 bash scripts/review-poll.sh

7) Auto-polling: making Codex check for messages

Codex won't poll on its own — it only acts when prompted. Options A–C below require a human in the loop to relay messages to Codex. Only Option D is fully automated.

Option A: Codex custom instructions (requires human)

Add to .github/copilot-instructions.md or your VS Code Copilot instructions:

After completing any task, call the fetch_messages MCP tool on the "proj-x" chann