Claude Codex MCP Relay

You run a single Python MCP server that lets Claude Code and Codex connect, share conversations, and review code through a lightweight web UI and a set of MCP tools. It includes post_message, fetch_messages, and list_channels, while keeping a log of tool usage and offering a small web interface to view conversations and highlighted code blocks.

How to use

To use this MCP relay, start the server on your machine and connect your MCP clients to the provided MCP endpoint. Claude Code and Codex can both read from and write to the same channel, enabling a collaborative review workflow with automatic logging and a simple web UI to inspect conversations and fenced code.

How to install

Prerequisites: Python 3.10 or newer and pip.

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

Configuration and operation

The MCP server reads configuration from a JSON file named config.json if present, or from environment variables, or falls back to sensible defaults.

Key configuration options you will likely use directly include host, port, log_path, and channels. The default local endpoint is http://127.0.0.1:8010 with the MCP path at /mcp, and the web UI available at /.

# Example: start the HTTP endpoint via UVicorn
uvicorn claude_codex:app --host 127.0.0.1 --port 8010

# Or start the Python script directly (reads host/port from config.json or env vars)
python claude_codex.py

Configuration options

Configuration can be supplied in two ways: a config.json file or environment variables. The JSON file is preferred for bulk setups, while environment variables are convenient for quick runs or containerized deployments.

{
  "host": "127.0.0.1",
  "port": 8010,
  "log_path": "claude_codex.log",
  "log_max_bytes": 5242880,
  "log_backup_count": 10,
  "channels": ["proj-x", "codex", "claude"],
  "allowed_hosts": []
}

MCP access details

The MCP endpoint is exposed at the http URL and can be hit by MCP clients. The web UI is available at the root web path, and MCP operations happen via the /mcp path.

Security and networking notes

To allow remote machines to connect, you can set allowed_hosts in the config.json (or the corresponding environment variable) to include the remote IPs. Be mindful of network exposure and only allow trusted clients to connect.

Notes

This server stores messages in memory. Restarting clears the history. If you need persistence, replace in-memory storage with a database like SQLite or Redis while keeping the same MCP tools and endpoints.

Available tools

post_message

Send a message to a channel through the MCP relay, used to publish reviews or updates.

fetch_messages

Retrieve recent messages from a channel to review feedback or new contributions.

list_channels

List available channels in the MCP relay to determine where to post or fetch messages.