### Install Codex CLI

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/codex-cli-integration.md

Install the Codex CLI for new users using npm or Homebrew.

```bash
npm install -g @openai/codex
```

```bash
brew install codex
```

--------------------------------

### Development Setup for Codex MCP Server

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/README.md

Commands to set up the development environment for the Codex MCP Server, including installing dependencies, running in development mode, building for production, and running tests.

```bash
npm install    # Install dependencies
npm run dev    # Development mode
npm run build  # Build for production
npm test       # Run tests
```

--------------------------------

### Test Codex CLI Setup

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/codex-cli-integration.md

Execute a simple command to verify the Codex CLI setup and execution environment.

```bash
codex exec --skip-git-repo-check "console.log('Hello, Codex!')"
```

--------------------------------

### Example List Sessions Response

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/api-reference.md

An example response from the listSessions tool, showing a list of active conversation sessions with their metadata.

```json
{
  "content": [{
    "type": "text",
    "text": "[
  {
    \"id\": \"abc-123-def\",
    \"createdAt\": \"2025-01-01T12:00:00.000Z\",
    \"lastAccessedAt\": \"2025-01-01T12:30:00.000Z\",
    \"turnCount\": 5
  }
]"
  }]
}
```

--------------------------------

### Ping Server Response Example

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/api-reference.md

Example response from the ping tool, showing the echoed message. This confirms the server is active and responsive.

```json
{
  "content": [{
    "type": "text",
    "text": "Hello, server!"
  }]
}
```

--------------------------------

### Codex CLI Example Commands

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/plan.md

Illustrates common use cases for the Codex CLI, demonstrating how to prompt for code explanation, refactoring, and error handling.

```bash
# All requests use the same simple pattern
codex exec "Explain this TypeScript function"
codex exec "Refactor this code for better performance"  
codex exec "Add error handling to this function"
```

--------------------------------

### Install and Login to Codex CLI

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/README.md

Install the Codex CLI globally and log in using your OpenAI API key. This is a prerequisite for using the Codex MCP Server.

```bash
npm i -g @openai/codex
codex login --api-key "your-openai-api-key"
```

--------------------------------

### Install Codex CLI and Login

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Install the Codex CLI globally and log in using your OpenAI API key. Ensure you are using v0.75.0 or later.

```bash
# Install Codex CLI (v0.75.0+ required)
npm i -g @openai/codex
codex login --api-key "your-openai-api-key"
```

--------------------------------

### Ping Server Example

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/api-reference.md

Send a message to the MCP server to test connection and responsiveness. The server echoes the provided message.

```json
{
  "message": "Hello, server!"
}
```

--------------------------------

### Install Codex CLI via Homebrew

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/README.md

Alternative installation method for the Codex CLI using Homebrew. Ensure you have Homebrew installed.

```bash
brew install codex
```

--------------------------------

### Basic Codex CLI Usage Examples

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/README.md

Examples of how to use the Codex CLI for common tasks like code explanation, refactoring, and reviewing uncommitted changes.

```bash
Ask codex to explain this function
Use codex to refactor this code for better performance
Use review to check my uncommitted changes
```

--------------------------------

### help Tool

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Fetches and returns the output of `codex --help`, providing a real-time reference to CLI flags, subcommands, and available options for the installed Codex CLI version.

```APIDOC
## Tool: `help` — Codex CLI Documentation

Fetches and returns the output of `codex --help`, providing a real-time reference to CLI flags, subcommands, and available options for the installed Codex CLI version.

### Parameters

This tool does not accept any parameters.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "help",
    "arguments": {}
  }
}
```

### Response Example
```json
{ "content": [{ "type": "text", "text": "Usage: codex [options] <command>\n..." }] }
```
```

--------------------------------

### Basic Codex Tool Usage

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/api-reference.md

A simple example of invoking the codex tool with a prompt. Use this for straightforward requests.

```json
{
  "prompt": "Explain this Python function and suggest improvements"
}
```

--------------------------------

### List Sessions Tool - Response (Active Sessions)

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Example response from the `listSessions` tool when active sessions are present. It lists session IDs, creation times, last access times, and turn counts.

```json
{
  "content": [
    {
      "type": "text",
      "text": "[
  {
    \"id\": \"auth-refactor\",
    \"createdAt\": \"2025-07-14T09:00:00.000Z\",
    \"lastAccessedAt\": \"2025-07-14T10:15:00.000Z\",
    \"turnCount\": 7
  },
  {
    \"id\": \"perf-review\",
    \"createdAt\": \"2025-07-14T08:30:00.000Z\",
    \"lastAccessedAt\": \"2025-07-14T09:45:00.000Z\",
    \"turnCount\": 3
  }
]"
    }
  ]
}
```

--------------------------------

### Construct Code Review Command (TypeScript)

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/codex-cli-integration.md

Provides an example of constructing a command for code review using the 'review' subcommand, including specifying the working directory and model configuration.

```typescript
['-C', workingDir, 'review', '-c', 'model="modelName"', '--uncommitted', '--base', 'main', prompt]
```

--------------------------------

### Codex CLI: Basic Execution

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Use this command for basic execution of a prompt with a specified model. Ensure the Codex CLI is installed and authenticated.

```bash
codex exec --model gpt-5.3-codex --skip-git-repo-check "your prompt"
```

--------------------------------

### Send Progress Updates in Handlers

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/CLAUDE.md

Example of how to send progress updates from tool handlers using the progress context. Ensure the progress context is created from the request metadata.

```typescript
// In server.ts - progress context is created from request._meta?.progressToken
const context = createProgressContext();

// In handlers - send progress updates
await context.sendProgress('Processing...', 1, 10);
```

--------------------------------

### Progress Notification

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/api-reference.md

This is an example of a progress notification message sent by the server during the execution of a long-running operation.

```json
{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "progressToken": "unique-token-123",
    "progress": 1,
    "message": "Processing output from Codex..."
  }
}
```

--------------------------------

### Check Codex CLI Version

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/codex-cli-integration.md

Use this command to check the currently installed version of the Codex CLI.

```bash
codex --version
```

--------------------------------

### Help Tool - Request

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Fetch the documentation for the Codex CLI by calling the `help` tool. This provides real-time information on available commands and options.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "help",
    "arguments": {}
  }
}
```

--------------------------------

### Build and Run Development Commands

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/CLAUDE.md

Commands for building the project, running in development mode, executing tests, and performing linting/formatting.

```bash
npm run build

# Development mode (runs src/index.ts directly with tsx)
npm run dev

# Run tests
npm test                # Run all tests
npm run test:watch      # Watch mode
npm run test:coverage   # With coverage report

# Run a single test file
npx jest src/__tests__/context-building.test.ts

# Linting and formatting
npm run lint          # ESLint
npm run lint:fix      # Auto-fix lint issues
npm run format        # Prettier
make lint             # Run both lint and format
```

--------------------------------

### Construct Exec Command with Sandbox (TypeScript)

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/codex-cli-integration.md

Shows how to construct an 'exec' command with advanced parameters, including sandbox mode, full auto execution, and specifying a working directory.

```typescript
['exec', '--model', selectedModel, '--sandbox', 'workspace-write', '--full-auto', '-C', workingDir, '--skip-git-repo-check', prompt]
```

--------------------------------

### Codex Tool Session Reset

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/api-reference.md

Reset a conversation session to start fresh. Use this when you need to clear the context and begin a new topic.

```json
{
  "prompt": "Start fresh analysis",
  "sessionId": "my-coding-session",
  "resetSession": true
}
```

--------------------------------

### Basic Session Usage with Codex CLI

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/session-management.md

Demonstrates explicit session management by providing a sessionId, which creates the session on first use. Includes an option to reset session history.

```bash
# Explicit session management (creates the session on first use)
codex --sessionId "auth-review" "Continue analysis"
codex --sessionId "auth-review" --resetSession true "Start fresh review"
```

--------------------------------

### Construct Resume Command (TypeScript)

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/codex-cli-integration.md

Demonstrates the command structure for resuming a conversation using 'exec resume', emphasizing that all 'exec' options must precede the 'resume' subcommand.

```typescript
['exec', '--skip-git-repo-check', '-c', 'model="modelName"', '-c', 'model_reasoning_effort="high"', 'resume', conversationId, prompt]
```

--------------------------------

### Advanced Codex CLI Configuration

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/session-management.md

Shows how to control the AI model and reasoning effort for complex tasks. Also demonstrates session management with custom parameters and listing active sessions.

```bash
# Model and reasoning control
codex --model "gpt-4" --reasoningEffort "high" "Complex architectural analysis"

# Session with custom parameters
codex --sessionId "deep-dive" --model "gpt-4" --reasoningEffort "high" "Advanced optimization review"

# Session management
listSessions  # View all active sessions
```

--------------------------------

### Construct Basic Exec Command (TypeScript)

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/codex-cli-integration.md

Illustrates the basic structure for executing a prompt using the 'exec' subcommand with a specified model and skipping the Git repository check.

```typescript
['exec', '--model', selectedModel, '--skip-git-repo-check', prompt]
```

--------------------------------

### help

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/api-reference.md

Retrieves information about Codex CLI capabilities and commands by executing `codex --help`.

```APIDOC
## help - Codex CLI Help

### Description
Get information about Codex CLI capabilities and commands.

### Parameters
No parameters required.

### Response
Returns the output of `codex --help` command, providing comprehensive CLI documentation.
```

--------------------------------

### Construct Code Review Command with Config Before (TypeScript)

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/codex-cli-integration.md

An alternative way to construct a code review command where model configuration is provided as a global option before the 'review' subcommand.

```typescript
['-C', workingDir, '-c', 'model="modelName"', 'review', '--uncommitted', '--base', 'main', prompt]
```

--------------------------------

### Codex CLI: Help Command

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Display the help information for the Codex CLI. This is useful for understanding available commands and options.

```bash
codex --help
```

--------------------------------

### Web Search Tool - Basic Query

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Perform a basic web search using the `websearch` tool. Specify the search query in the arguments.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "websearch",
    "arguments": {
      "query": "TypeScript 5.8 new features and breaking changes"
    }
  }
}
```

--------------------------------

### List Sessions Tool - Request

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Request metadata for all active in-memory sessions. This tool requires no arguments.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "listSessions",
    "arguments": {}
  }
}
```

--------------------------------

### Codex CLI: Web Search

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Perform a web search using the 'exec' subcommand with the '--search' flag. The prompt should clearly state the search query and desired output.

```bash
codex --search exec --skip-git-repo-check "Search for: TypeScript 5.8 features. Provide 10 key findings."
```

--------------------------------

### Codex CLI: Execution with Sandbox and Scoping

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Execute a prompt within a sandbox environment, with full auto mode, and scoped to a specific directory. The '-C' flag specifies the project path.

```bash
codex exec --model gpt-5.3-codex --sandbox workspace-write --full-auto -C /abs/path/to/project --skip-git-repo-check "prompt"
```

--------------------------------

### Codex CLI: Review Branch Comparison

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Compare a branch against a base branch for review, with custom instructions and a title. The '-C' flag specifies the repository path.

```bash
codex -C /abs/path/to/repo -c 'model="gpt-4"' review --base main --title "Security Audit" "Focus on SQL injection"
```

--------------------------------

### Codex CLI: Execution with Reasoning Effort

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Execute a prompt with a specified model and reasoning effort. The '-c' flag is used to pass configuration options.

```bash
codex exec --model gpt-5.3-codex -c 'model_reasoning_effort="high"' --skip-git-repo-check "prompt"
```

--------------------------------

### Code Review with Codex CLI

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/README.md

Utilize the `review` tool for code reviews. You can specify a base branch or review uncommitted local changes.

```bash
Use review with base "main" to check my PR changes
Use review with uncommitted true to review my local changes
```

--------------------------------

### Web Search with Codex CLI

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/README.md

Perform web searches using the `websearch` tool. Customize the query, number of results, and search depth.

```bash
Use websearch with query "TypeScript 5.8 new features"
Use websearch with query "Rust vs Go performance 2025" and numResults 15
Use websearch with query "React Server Components" and searchDepth "full"
```

--------------------------------

### Configure Claude Desktop MCP Server

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/api-reference.md

Add this JSON configuration to your Claude Desktop settings to connect to the codex-cli MCP server.

```json
{
  "mcpServers": {
    "codex-cli": {
      "command": "npx",
      "args": ["-y", "codex-mcp-server"]
    }
  }
}
```

--------------------------------

### List Sessions Tool - Response (No Sessions)

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Response from the `listSessions` tool when no active sessions are found.

```json
{
  "content": [
    {
      "type": "text",
      "text": "No active sessions"
    }
  ]
}
```

--------------------------------

### Run Codex MCP Server Directly

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Execute the Codex MCP Server directly using npx for testing purposes. This is useful for quick verification without formal registration.

```bash
# Or run directly for testing
npx -y codex-mcp-server
```

--------------------------------

### Review a Pull Request Branch Against Base

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Analyze a pull request branch against a base branch (e.g., `main`) with custom instructions. Specify a title for the review and select a model.

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "review",
    "arguments": {
      "base": "main",
      "prompt": "Focus on SQL injection risks and missing input validation",
      "title": "Security Audit — PR #142",
      "model": "gpt-4"
    }
  }
}
```

--------------------------------

### ping Tool

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Tests server connectivity by echoing back a provided message or the default 'pong'. Useful for verifying the MCP server is alive and responsive.

```APIDOC
## Tool: `ping` — Connection Health Check

Tests server connectivity by echoing back the provided message (or `"pong"` by default). Useful for verifying the MCP server is alive and responsive before initiating longer operations.

### Parameters

- `message` (string) - Optional - The message to echo back. Defaults to `"pong"`.

### Request Example (Default Ping)
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ping",
    "arguments": {}
  }
}
```

### Response Example (Default Ping)
```json
{ "content": [{ "type": "text", "text": "pong" }] }
```

### Request Example (Custom Message)
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "ping",
    "arguments": { "message": "health-check-ok" }
  }
}
```

### Response Example (Custom Message)
```json
{ "content": [{ "type": "text", "text": "health-check-ok" }] }
```
```

--------------------------------

### Integrate Codex CLI with Claude MCP

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/plan.md

Shows how to add the Codex CLI as a tool to the Claude MCP system, enabling single-command Claude integration.

```bash
claude mcp add codex-cli -- npx -y codex-mcp-server
```

--------------------------------

### Codex Server Environment Variables

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Lists environment variables that can be used to configure the Codex server's behavior, such as the default model, callback URI, and structured content generation.

```bash
# Optional: override default model for all tools (takes precedence over hardcoded default, overridden by per-request 'model' param)
export CODEX_DEFAULT_MODEL="gpt-4o"

# Optional: static MCP callback URI forwarded to Codex CLI (overridden by per-request 'callbackUri' param)
export CODEX_MCP_CALLBACK_URI="http://localhost:1234/mcp-callback"

# Optional: enable structuredContent in tool responses (disabled by default to avoid Claude Code SDK bug)
export STRUCTURED_CONTENT_ENABLED="true"   # accepts: 1, true, yes, on
```

--------------------------------

### Ping Tool - Default Request

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Send a default ping request to the server to check connectivity. The server will respond with 'pong'.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ping",
    "arguments": {}
  }
}
```

--------------------------------

### Review Changes Against Main Branch

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/api-reference.md

Perform a code review focusing on specific areas like security vulnerabilities, comparing against the 'main' branch. Provide custom instructions in the 'prompt' field.

```json
{
  "base": "main",
  "prompt": "Focus on security vulnerabilities"
}
```

--------------------------------

### Authenticate Codex CLI

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/codex-cli-integration.md

Log in to the Codex CLI using your OpenAI API key.

```bash
codex login --api-key "your-openai-api-key"
```

--------------------------------

### Advanced Codex CLI Options

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/README.md

Configure advanced options for the `codex` tool, including model selection, reasoning effort, automated task execution, and callback URIs.

```bash
Use codex with model "o3" and reasoningEffort "high" for complex analysis
Use codex with fullAuto true and sandbox "workspace-write" for automated tasks
Use codex with callbackUri "http://localhost:1234/callback" for static callbacks
Use codex to return structuredContent with threadId metadata when available
```

--------------------------------

### Test Codex CLI Features

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/codex-cli-integration.md

Commands to test code review and sandbox execution features of the Codex CLI.

```bash
codex review --uncommitted
```

```bash
codex exec --sandbox workspace-write --skip-git-repo-check "list files"
```

--------------------------------

### Session Data Structure and API

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Defines the structure for session data and demonstrates the API for managing sessions in memory. Use this for creating, updating, and retrieving session information.

```typescript
interface SessionData {
  id: string;
  createdAt: Date;
  lastAccessedAt: Date;
  turns: ConversationTurn[];
  codexConversationId?: string; // Extracted from CLI stderr, used for native resume
}

interface ConversationTurn {
  prompt: string;
  response: string;
  timestamp: Date;
}
```

```typescript
// Usage pattern — InMemorySessionStorage API
import { InMemorySessionStorage } from './src/session/storage.js';

const storage = new InMemorySessionStorage();

// Create or touch a named session
storage.ensureSession('my-session'); // creates if not exists, updates lastAccessedAt if exists

// Record a conversation turn
storage.addTurn('my-session', {
  prompt: 'Explain this function',
  response: 'This function does X because...', 
  timestamp: new Date(),
});

// Store native Codex conversation ID for resume
storage.setCodexConversationId('my-session', 'conv_abc123def');

// Retrieve the conversation ID for resume mode
const convId = storage.getCodexConversationId('my-session');
// convId → 'conv_abc123def'

// List all active sessions (sorted by lastAccessedAt desc, expired removed)
const sessions = storage.listSessions();
// [{ id: 'my-session', createdAt: Date, lastAccessedAt: Date, turns: [...], codexConversationId: 'conv_abc123def' }]

// Reset a session (clears turns and conversationId, keeps session alive)
storage.resetSession('my-session');

// Permanently delete
storage.deleteSession('my-session'); // returns true if found
```

--------------------------------

### Ping Tool - Custom Echo Request

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Send a ping request with a custom message to verify server responsiveness. The server echoes the provided message.

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "ping",
    "arguments": { "message": "health-check-ok" }
  }
}
```

--------------------------------

### listSessions Tool

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Returns metadata for all active in-memory sessions, sorted by most-recently-accessed. Sessions expire after 24 hours of inactivity and the server holds a maximum of 100 concurrent sessions.

```APIDOC
## Tool: `listSessions` — Session Introspection

Returns metadata for all active in-memory sessions, sorted by most-recently-accessed. Sessions are created automatically when a `sessionId` is first passed to the `codex` tool and expire after 24 hours of inactivity. The server holds a maximum of 100 concurrent sessions.

### Parameters

This tool does not accept any parameters.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "listSessions",
    "arguments": {}
  }
}
```

### Response Example (Active Sessions)
```json
{
  "content": [
    {
      "type": "text",
      "text": "[
  {
    "id": "auth-refactor",
    "createdAt": "2025-07-14T09:00:00.000Z",
    "lastAccessedAt": "2025-07-14T10:15:00.000Z",
    "turnCount": 7
  },
  {
    "id": "perf-review",
    "createdAt": "2025-07-14T08:30:00.000Z",
    "lastAccessedAt": "2025-07-14T09:45:00.000Z",
    "turnCount": 3
  }
]"
    }
  ]
}
```

### Response Example (No Sessions)
```json
{
  "content": [
    {
      "type": "text",
      "text": "No active sessions"
    }
  ]
}
```
```

--------------------------------

### Error Response and Handling

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Illustrates the structure of error responses and the hierarchy of custom error classes for handling tool execution failures. Errors are returned as tool results, not JSON-RPC errors.

```typescript
// Error response shape
{
  content: [{ type: 'text', text: 'Error in tool "codex": Failed to execute codex command (spawn codex ENOENT)' }],
  isError: true
}
```

```typescript
// Error class hierarchy (src/errors.ts)
import { ToolExecutionError, CommandExecutionError, ValidationError, handleError } from './src/errors.js';

// ToolExecutionError — tool handler failed
throw new ToolExecutionError('codex', 'Failed to execute codex command', originalError);
// message: 'Failed to execute tool "codex": Failed to execute codex command (spawn ENOENT)'

// CommandExecutionError — child process failure
throw new CommandExecutionError('codex exec --skip-git-repo-check "prompt"', 'Command failed with exit code 1', stderrError);
// message: 'Command execution failed for "codex exec ...": Command failed with exit code 1'

// ValidationError — bad input parameters
throw new ValidationError('codex', 'Session ID must be 1-256 characters and contain only letters, numbers, hyphens, and underscores');
// message: 'Validation failed for tool "codex": Session ID must be ...'

// Generic error formatter
const msg = handleError(unknownError, 'tool "review"');
// Returns 'Error in tool "review": <error.message or String(error)>'
```

--------------------------------

### Perform AI Code Review on Uncommitted Changes

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Use the `review` tool to analyze uncommitted changes in your working tree. This includes staged, unstaged, and untracked files.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "review",
    "arguments": {
      "uncommitted": true
    }
  }
}
```

--------------------------------

### listSessions

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/api-reference.md

Lists all active conversation sessions with their metadata, including creation time, last access time, and turn count.

```APIDOC
## listSessions - Session Management

### Description
List all active conversation sessions with metadata.

### Parameters
No parameters required.

### Response Format
```typescript
interface SessionInfo {
  id: string;
  createdAt: string; // ISO 8601 timestamp
  lastAccessedAt: string; // ISO 8601 timestamp
  turnCount: number;
}
```

### Example Response
```json
{
  "content": [{
    "type": "text",
    "text": "[
  {
    "id": "abc-123-def",
    "createdAt": "2025-01-01T12:00:00.000Z",
    "lastAccessedAt": "2025-01-01T12:30:00.000Z",
    "turnCount": 5
  }
]"
  }]
}
```
```

--------------------------------

### Progress Notification Structure

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Defines the JSON structure for progress notifications sent during tool execution. Clients should include a `progressToken` in requests to receive these updates.

```json
// Request with progress token
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "codex",
    "arguments": { "prompt": "Analyze the entire codebase for performance bottlenecks" },
    "_meta": { "progressToken": "op-token-42" }
  }
}
```

```json
// Progress notification emitted during execution
{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "progressToken": "op-token-42",
    "progress": 3,
    "message": "Scanning module dependencies..."
  }
}
```

```json
// Final notification
{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "progressToken": "op-token-42",
    "progress": 4,
    "message": "[Completed] Found 3 critical bottlenecks in db/queries.ts..."
  }
}
```

--------------------------------

### Request with Progress Token

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/api-reference.md

Include a `progressToken` in the `_meta` field of your request to receive progress notifications for long-running operations.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "codex",
    "arguments": { "prompt": "Analyze this codebase" },
    "_meta": { "progressToken": "unique-token-123" }
  }
}
```

--------------------------------

### Web Search Tool - Deep Search Configuration

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Execute a deep web search with an increased number of results and full search depth. This allows for more comprehensive information gathering.

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "websearch",
    "arguments": {
      "query": "Rust vs Go performance benchmarks 2025",
      "numResults": 20,
      "searchDepth": "full"
    }
  }
}
```

--------------------------------

### Code Analysis with Codex CLI

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/README.md

Use the `codex` tool to analyze code for specific issues, such as security vulnerabilities in authentication logic.

```bash
Use codex to analyze this authentication logic for security issues
```

--------------------------------

### Multi-turn Conversations with Session IDs

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/README.md

Manage multi-turn conversations using session IDs. Passing a sessionId creates or resumes a session, allowing for context persistence across multiple calls.

```bash
Use codex with sessionId "refactor" to analyze this module
Use codex with sessionId "refactor" to implement your suggestions
```

--------------------------------

### Codex CLI: Resume Mode Execution

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Resume a previous conversation or task. All execution flags must precede the 'resume' subcommand. Multiple '-c' flags can be used for configuration.

```bash
codex exec --skip-git-repo-check -c 'model="gpt-5.3-codex"' -c 'model_reasoning_effort="high"' resume conv_abc123def "follow-up prompt"
```

--------------------------------

### Codex CLI Core Execution Pattern

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/plan.md

This is the fundamental command structure for executing prompts with the Codex CLI. It's used for various tasks like code explanation, refactoring, and error handling.

```bash
codex exec "prompt"
```

--------------------------------

### List Sessions Response Format

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/api-reference.md

Defines the structure for session information returned by the listSessions tool. Each session includes an ID, creation timestamp, last access time, and turn count.

```typescript
interface SessionInfo {
  id: string;
  createdAt: string; // ISO 8601 timestamp
  lastAccessedAt: string; // ISO 8601 timestamp
  turnCount: number;
}
```

--------------------------------

### Review Tool Expected Response Shape

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

The response from the `review` tool contains the code review summary, including identified issues and metadata about the review.

```json
{
  "content": [
    {
      "type": "text",
      "text": "## Code Review: Security Audit — PR #142\n\n### Issues Found\n1. Unsanitized user input on line 42...",
      "_meta": {
        "model": "gpt-4",
        "base": "main"
      }
    }
  ]
}
```

--------------------------------

### Register Codex MCP Server with Claude Code

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Register the Codex MCP Server as an MCP tool in Claude Code. This command allows Claude Code to discover and utilize the server's capabilities.

```bash
# Register with Claude Code
claude mcp add codex-cli -- npx -y codex-mcp-server
```

--------------------------------

### ping

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/api-reference.md

Tests the MCP server connection and responsiveness by echoing back a provided message.

```APIDOC
## ping - Connection Test

### Description
Test MCP server connection and responsiveness.

### Parameters
#### Query Parameters
- **message** (string) - Optional - Message to echo back (defaults to `pong`)

### Example
```json
{
  "message": "Hello, server!"
}
```

### Response
```json
{
  "content": [{
    "type": "text",
    "text": "Hello, server!"
  }]
}
```
```

--------------------------------

### Codex Command Structure: Resume Mode

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/CLAUDE.md

Structure for building Codex CLI commands in 'resume' mode for existing conversations. Config flags must precede the 'resume' subcommand.

```bash
codex exec --skip-git-repo-check -c model="X" -c model_reasoning_effort="Y" resume <conversation-id> "prompt"
```

--------------------------------

### Web Search Tool - Expected Response

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

The structure of the response from the `websearch` tool, including summarized content and metadata about the search performed.

```json
{
  "content": [
    {
      "type": "text",
      "text": "Based on web search results for 'TypeScript 5.8 new features':\n\n1. Enhanced type inference...",
      "_meta": {
        "query": "TypeScript 5.8 new features and breaking changes",
        "numResults": 10,
        "searchDepth": "basic",
        "timestamp": "2025-07-14T10:30:00.000Z"
      }
    }
  ]
}
```

--------------------------------

### Codex CLI: Review Specific Commit

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Review a specific commit using its hash. The '-c' flag can be used to specify the model and a title can be provided.

```bash
codex -c 'model="gpt-5.3-codex"' review --commit a3f9c12d --title "Hotfix review"
```

--------------------------------

### Review a Specific Commit SHA

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Audit a particular commit by its SHA. You can also specify a working directory for the review context.

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "review",
    "arguments": {
      "commit": "a3f9c12d",
      "title": "Hotfix review",
      "workingDirectory": "/home/user/repo"
    }
  }
}
```

--------------------------------

### Execute Codex CLI in Non-Interactive Mode

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Use this for AI-powered code analysis, generation, and refactoring. Supports multi-turn conversations, model selection, and sandbox policies.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "codex",
    "arguments": {
      "prompt": "Analyze this authentication function for security issues and suggest fixes"
    }
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "codex",
    "arguments": {
      "prompt": "Perform a deep architectural review of this microservices design",
      "model": "o3",
      "reasoningEffort": "high"
    }
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "codex",
    "arguments": {
      "prompt": "Now refactor the auth module based on your suggestions",
      "sessionId": "auth-refactor"
    }
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "codex",
    "arguments": {
      "prompt": "Add TypeScript strict mode and fix all resulting type errors",
      "fullAuto": true,
      "sandbox": "workspace-write",
      "workingDirectory": "/home/user/my-project"
    }
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "codex",
    "arguments": {
      "prompt": "Start a new review of the payment module",
      "sessionId": "auth-refactor",
      "resetSession": true
    }
  }
}
```

--------------------------------

### Review Specific Commit

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/api-reference.md

Conduct a code review for a particular commit SHA, optionally providing a title for the review summary. This is useful for auditing specific changes.

```json
{
  "commit": "abc123def",
  "title": "Security Audit"
}
```

--------------------------------

### Codex CLI: Review Uncommitted Changes

Source: https://context7.com/tuannvm/codex-mcp-server/llms.txt

Review uncommitted changes in the repository. The '-c' flag can be used to specify the model.

```bash
codex -c 'model="gpt-5.3-codex"' review --uncommitted
```

--------------------------------

### Review Tool Response Format

Source: https://github.com/tuannvm/codex-mcp-server/blob/main/docs/api-reference.md

Defines the structure of the response from the review tool, including review output and metadata. The `structuredContent` is optional and depends on server configuration.

```typescript
interface ReviewToolResponse {
  content: Array<{ 
    type: 'text';
    text: string; // Review output from Codex
    _meta?: {
      model: string;
      base?: string;
      commit?: string;
    };
  }>;
  structuredContent?: {
    model: string;
    base?: string;
    commit?: string;
  };
}
```