Codex MCP Server

An open-source Model Context Protocol server that bridges MCP clients (Claude Desktop, Cursor, Poke, etc.) with the Codex CLI running on your machine.

Run coding tasks, manage conversation threads, fork sessions, and browse historical rolls — all through standard MCP tooling.

Prerequisites

• Node.js 22+ (required for native SQLite bindings)
• Codex CLI installed and authenticated — verify with codex doctor

Quick Start

git clone https://github.com/4dhxm/codex-mcp-server.git
cd codex-mcp-server
npm install
npm run build

Running the Server

1. Local Transport (stdio)

For MCP clients running on the same machine (like Claude Desktop or Cursor).

node dist/index.js

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "codex": {
      "command": "node",
      "args": ["/absolute/path/to/codex-mcp-server/dist/index.js"]
    }
  }
}

2. Remote Transport with Auto-Tunnel (Streamable HTTP + Cloudflare)

For exposing your local Codex installation to remote MCP clients (like Poke or a remote device) without dealing with routers or ngrok warning pages.

Dependency: You must have cloudflared installed. On macOS:

brew install cloudflared

node dist/index.js --http --tunnel

This starts the server and automatically spawns a free, highly-stable Cloudflare Quick Tunnel.

You can also explicitly set your API key:

node dist/index.js --http --tunnel --api-key my-secret-token

You will see output like this:

==============================================
🌐 Cloudflare tunnel established successfully!
Public URL: https://some-random-words.trycloudflare.com
MCP URL:    https://some-random-words.trycloudflare.com/mcp
==============================================

Connect from your remote MCP client:

URL:     https://some-random-words.trycloudflare.com/mcp
Type:    Streamable HTTP
Auth:    Bearer <your-api-key>

3. Local HTTP Network Transport

To run over HTTP without a public tunnel (for your local network):

node dist/index.js --http --port 8080

Authentication

API key auth is enabled by default for HTTP mode to protect your local machine from unauthorized remote access.

Provide a key via --api-key <key> flag or CODEX_MCP_API_KEY env var. If neither is set, a random secure key is generated and printed on startup.

How clients send the key — any of these work:

Method	Example
Authorization header	Authorization: Bearer sk-abc123
x-api-key header	x-api-key: sk-abc123
Query parameter	?apiKey=sk-abc123

The server intentionally avoids returning WWW-Authenticate headers to prevent MCP clients from attempting OAuth flows, ensuring simple Bearer token auth works cleanly.

Tools

Tool	Description
codex_task / codex_run	Run a coding task in a new thread
codex_start_thread	Initialize a thread without running a turn
codex_run_turn / codex_continue	Send a follow-up prompt to an existing thread
codex_list_threads	List active/archived threads from local SQLite
codex_get_thread	Get metadata and conversation history
codex_fork_thread	Clone a thread's history into a new session
codex_archive_thread	Archive a thread
codex_unarchive_thread	Unarchive a thread
codex_interrupt / codex_interrupt_turn	Abort a running turn

License

Apache 2.0