API Reference

January 25, 2026 · View on GitHub

Overview

Complete reference for the Codex MCP Server tools and interfaces.

This server implements the MCP 2025-11-25 specification, including tool annotations and progress notifications.

Installation Options

Claude Code

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

Claude Desktop

Add to your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%/Claude/claude_desktop_config.json

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

MCP Protocol Features

Tool Annotations

All tools include annotations that provide hints to MCP clients about tool behavior:

Annotation	Type	Description
`title`	string	Human-readable tool name
`readOnlyHint`	boolean	Tool doesn't modify state (safe to call)
`destructiveHint`	boolean	Tool may modify files or external state
`idempotentHint`	boolean	Multiple calls produce same result
`openWorldHint`	boolean	Tool interacts with external services (network, APIs)

Tool Annotation Matrix

Tool	`title`	`readOnlyHint`	`destructiveHint`	`idempotentHint`	`openWorldHint`
`codex`	Execute Codex CLI	`false`	`true`	`false`	`true`
`review`	Code Review	`true`	`false`	`true`	`true`
`ping`	Ping Server	`true`	`false`	`true`	`false`
`help`	Get Help	`true`	`false`	`true`	`false`
`listSessions`	List Sessions	`true`	`false`	`true`	`false`

Progress Notifications

For long-running operations, the server sends notifications/progress messages when the client includes a progressToken in the request _meta.

Request with Progress Token:

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

Progress Notification (sent during execution):

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

Supported Tools: codex, review (long-running operations)

Note: Progress notifications are streamed in real-time from CLI stdout/stderr. Client support for displaying these notifications varies.

Tools

`codex` - AI Coding Assistant

Execute Codex CLI with advanced session management and model control.

Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true

Parameters

Parameter	Type	Required	Default	Description
`prompt`	string	✅	-	The coding task, question, or analysis request
`sessionId`	string	❌	-	Session ID for conversational context
`resetSession`	boolean	❌	`false`	Reset session history before processing
`model`	string	❌	`gpt-5.2-codex`	Model to use for processing
`reasoningEffort`	enum	❌	-	Control reasoning depth
`sandbox`	enum	❌	-	Sandbox policy: `read-only`, `workspace-write`, `danger-full-access`
`fullAuto`	boolean	❌	`false`	Enable full-auto mode (sandboxed automatic execution)
`workingDirectory`	string	❌	-	Working directory for the agent
`callbackUri`	string	❌	-	Static MCP callback URI passed via env to Codex

Model Options

gpt-5.2-codex (default) - Latest specialized coding model optimized for agentic tasks
gpt-5.1-codex - Previous coding model version
gpt-5.1-codex-max - Enhanced coding model for complex tasks
gpt-5-codex - Base GPT-5 coding model
gpt-4o - Fast multimodal model
gpt-4 - Advanced reasoning capabilities

Reasoning Effort Levels

low - Quick responses, minimal processing
medium - Balanced quality and speed
high - Thorough analysis and comprehensive responses

Response Format

interface CodexToolResponse {
  content: Array<{
    type: 'text';
    text: string;
    _meta?: {
      threadId?: string;
      model?: string;
      sessionId?: string;
      callbackUri?: string;
    };
  }>;
  structuredContent?: {
    threadId?: string;
    model?: string;
    sessionId?: string;
    callbackUri?: string;
  };
}

Note: structuredContent is only emitted when STRUCTURED_CONTENT_ENABLED is set to a truthy value (1, true, yes, on). It is disabled by default. _meta remains available in content for Claude Code compatibility.

Output Schema (structuredContent)

The codex tool advertises an outputSchema that describes the structure of structuredContent returned in tool results when enabled.

{
  "type": "object",
  "properties": {
    "threadId": { "type": "string" }
  }
}

Examples

Basic Usage:

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

With Model Selection:

{
  "prompt": "Perform complex architectural analysis",
  "model": "gpt-4",
  "reasoningEffort": "high"
}

Session Management:

{
  "prompt": "Continue our previous discussion",
  "sessionId": "my-coding-session"
}

Reset Session:

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

`review` - Code Review

Run AI-powered code reviews against your repository using Codex CLI.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true

Parameters

Parameter	Type	Required	Default	Description
`prompt`	string	❌	-	Custom review instructions or focus areas
`uncommitted`	boolean	❌	`false`	Review staged, unstaged, and untracked changes
`base`	string	❌	-	Review changes against a specific base branch
`commit`	string	❌	-	Review changes introduced by a specific commit SHA
`title`	string	❌	-	Title to display in the review summary
`model`	string	❌	`gpt-5.2-codex`	Model to use for the review (passed via `-c model="..."`)
`workingDirectory`	string	❌	-	Working directory to run the review in (passed via `-C`)

Examples

Review Uncommitted Changes:

{
  "uncommitted": true
}

Review Against Main Branch:

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

Review Specific Commit:

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

Response Format

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;
  };
}

`listSessions` - Session Management

List all active conversation sessions with metadata.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

Parameters

No parameters required.

Response Format

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

Example Response

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

`ping` - Connection Test

Test MCP server connection and responsiveness.

Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

Parameters

Parameter	Type	Required	Default	Description
`message`	string	❌	`pong`	Message to echo back

Example

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

Response

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

Creation: Sessions are created automatically or explicitly via sessionId
Activity: Each interaction updates lastAccessedAt timestamp
Persistence: Sessions persist for 24 hours of inactivity
Cleanup: Automatic removal of expired sessions
Limits: Maximum 100 concurrent sessions

Session Data Structure

interface SessionData {
  id: string;                    // UUID-based session identifier
  createdAt: Date;              // Session creation timestamp
  lastAccessedAt: Date;         // Last interaction timestamp
  turns: ConversationTurn[];    // Conversation history
  codexConversationId?: string; // Native Codex conversation ID
}

interface ConversationTurn {
  prompt: string;    // User's original prompt
  response: string;  // Codex response
  timestamp: Date;   // Turn timestamp
}

Resume Functionality

The server leverages Codex CLI v0.50.0+ native resume functionality:

Conversation ID Extraction: Automatically captures conversation IDs from Codex output (supports both "session id" and "conversation id" formats)
Native Resume: Uses codex exec resume <conversation-id> for optimal continuity
Fallback Context: Manual context building when native resume unavailable
Seamless Integration: Transparent to end users

Error Handling

Error Response Format

interface ErrorResponse {
  content: Array<{
    type: 'text';
    text: string; // Error description
  }>;
  isError: true;
}

Common Error Scenarios

Authentication Errors

Cause: Codex CLI not authenticated
Message: "Authentication failed: Please run codex login"
Resolution: Run codex login --api-key "your-key"

Model Errors

Cause: Invalid or unavailable model specified
Message: "Invalid model: "
Resolution: Use supported model or omit for default

Session Errors

Cause: Corrupted session data or invalid session ID
Behavior: Graceful degradation, continues with fresh context
Impact: Minimal - system auto-recovers

CLI Errors

Cause: Codex CLI not installed or network issues
Message: "Failed to execute codex command"
Resolution: Install CLI and check network connectivity

Performance Considerations

Memory Management

Session TTL: 24-hour automatic cleanup
Session Limits: Maximum 100 concurrent sessions
Context Optimization: Recent turns only (last 2) for fallback context

Response Optimization

Model Selection: Default gpt-5.2-codex optimized for agentic coding
Reasoning Control: Adjust effort based on task complexity
Native Resume: Preferred over manual context building

Scalability

Stateless Design: Core functionality works without sessions
Graceful Degradation: Continues operation despite component failures
Resource Cleanup: Automatic management of memory and storage

Configuration

Environment Variables

None required - authentication handled by Codex CLI.

Optional:

CODEX_MCP_CALLBACK_URI: Static MCP callback URI passed to Codex CLI when invoking tools.

Codex CLI Requirements

Version: 0.36.0 or later
Authentication: codex login --api-key "your-key"
Verification: codex --help should execute successfully

Optional Configuration

CODEX_HOME: Custom directory for Codex CLI configuration
Session Limits: Configurable in server implementation (default: 100)
TTL Settings: Configurable session expiration (default: 24 hours)