codex-mcp

LanceVCS/codex-mcp

3.2

If you are the rightful owner of codex-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

An MCP server implementation using Codex CLI for reliable session ID tracking in multi-turn conversations.

Codex CLI-based MCP Server

An MCP server implementation that uses Codex CLI internally to provide reliable session ID tracking for multi-turn conversations.

Problem Solved

The native Codex MCP server (mcp__codex__codex) doesn't return session IDs, making it difficult to continue conversations using mcp__codex__codex_reply. This server uses the CLI with JSON output to get session IDs reliably.

How It Works

  1. Acts as an MCP server (speaks JSON-RPC protocol)
  2. Translates MCP codex tool calls to codex exec --json CLI commands
  3. Parses JSON output to extract session ID from thread.started event
  4. Returns both response text AND [SESSION_ID: xxx] to the client
  5. Translates MCP codex-reply calls to codex exec resume CLI commands

Prerequisites

  • Node.js 14.0 or higher
  • Codex CLI installed and configured
  • Claude Code installed

Installation

  1. Clone the repository to the standard MCP servers location:

    git clone <repo-url> ~/.claude/mcp-servers/codex-wrapper
cd ~/.claude/mcp-servers/codex-wrapper

  2. Add the MCP server to Claude Code:

# Add the wrapper to Claude Code
claude mcp add --transport stdio codex-wrapper -- node ~/.claude/mcp-servers/codex-wrapper/server.js

# Verify it's installed
claude mcp list

You should see codex-wrapper in the list with a ✓ Connected status.

Note: The wrapper will be available in your next Claude Code session. If you're in an active session, restart it to load the new MCP tools.

Usage

Once configured, use the MCP tools as normal. The response will include the session ID:

Response: "Here's the answer..."
[SESSION_ID: 019a7661-3643-7ac3-aeb9-098a910935fb]

Extract the ID and use it for follow-ups:

mcp__codex__codex_reply({
  conversationId: "019a7661-3643-7ac3-aeb9-098a910935fb",
  prompt: "follow-up question"
})

Advantages Over Native MCP

  • Reliable session IDs: Extracted directly from CLI JSON output, not guessed
  • No race conditions: No filesystem scanning or timing issues
  • Full compatibility: Uses the same CLI commands that work perfectly
  • Deterministic: Session ID is guaranteed to be correct

How It's Different

  • Native MCP: Doesn't return session IDs, can't continue conversations
  • This wrapper: Returns session IDs reliably by using CLI internally

Limitations

  • Slightly slower than native MCP (spawns CLI process)
  • Requires Node.js to run the wrapper