Skip to content

Latest commit

 

History

History
442 lines (351 loc) · 12.4 KB

api-reference.md

File metadata and controls

442 lines (351 loc) · 12.4 KB

API Reference

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

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.

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!"
  }]
}

help - Codex CLI Help

Get information about Codex CLI capabilities and commands.

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

Parameters

No parameters required.

Response

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

Session Management

Session Lifecycle

  1. Creation: Sessions are created automatically or explicitly via sessionId
  2. Activity: Each interaction updates lastAccessedAt timestamp
  3. Persistence: Sessions persist for 24 hours of inactivity
  4. Cleanup: Automatic removal of expired sessions
  5. 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:

  1. Conversation ID Extraction: Automatically captures conversation IDs from Codex output (supports both "session id" and "conversation id" formats)
  2. Native Resume: Uses codex exec resume <conversation-id> for optimal continuity
  3. Fallback Context: Manual context building when native resume unavailable
  4. 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)