# 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](https://github.com/codex-cli/codex) installed and configured
- Claude Code installed

## Installation

1. Clone the repository to the standard MCP servers location:
   ```bash
   git clone <repo-url> ~/.claude/mcp-servers/codex-wrapper
   cd ~/.claude/mcp-servers/codex-wrapper
   ```

2. Add the MCP server to Claude Code:

```bash
# 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:

```javascript
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