codex-mcp-server

Sessions in the Codex MCP Server follow a specific lifecycle:

1. Creation: Sessions are created automatically or explicitly via a provided sessionId.
2. Activity: Every interaction updates the lastAccessedAt timestamp.
3. Persistence: Sessions remain active for 24 hours of inactivity.
4. Cleanup: Expired sessions are removed automatically.
5. Limits: The server supports a maximum of 100 concurrent sessions.

The server uses Codex CLI v0.50+ native resume functionality by extracting conversation IDs from output and executing codex exec resume <conversation-id> to ensure seamless continuity.

Full-Auto mode enables sandboxed automatic execution without requiring manual approval prompts for every action. In the MCP tool, this is controlled by the fullAuto boolean parameter.

It is functionally equivalent to passing -a on-request --sandbox workspace-write to the CLI.

codex exec --full-auto --skip-git-repo-check "your prompt"

To control file system access during execution, use the --sandbox <mode> flag with the codex exec command. This is a parameter in the codex tool.

Modes:

• read-only: No file writes allowed.
• workspace-write: Writes are restricted to the workspace directory.
• danger-full-access: Full system access (use with caution).

Example:

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

The server is designed for scalability and efficient resource usage with the following characteristics:

Memory and Session Management

• Session TTL: Sessions are automatically cleaned up after 24 hours.
• Session Limits: The server supports a maximum of 100 concurrent sessions.
• Context Optimization: To optimize context, only the last 2 turns are used for fallback context.

Response and Scalability

• Model Selection: The default model is gpt-5.2-codex, which is optimized for agentic coding tasks.
• Stateless Design: Core functionality can operate without sessions.
• Graceful Degradation: The server continues to operate even if specific components fail.

The codex tool acts as a bridge between the MCP client (like Claude) and the local Codex CLI. When a tool call is made, the server executes the command using a child process.

Every request follows this core execution pattern:

codex exec "prompt"

Example usage patterns for the AI:

• codex exec "Explain this TypeScript function"
• codex exec "Refactor this code for better performance"
• codex exec "Add error handling to this function"

To continue a previous session, use the codex exec resume <conversation-id> command.

Important Constraints:

• The resume subcommand is part of exec.
• All exec options (like --skip-git-repo-check) must be placed BEFORE the resume subcommand.
• The --model flag is not available in resume mode; use -c model="<model-name>" instead.
• --sandbox and --full-auto are not available in resume mode.

Example:

codex exec --skip-git-repo-check -c model="gpt-5.2-codex" resume <conversation-id> "your prompt"

For Developers

• Always specify model explicitly when behavior consistency is critical.
• Use appropriate reasoning effort based on task complexity.
• Implement proper error handling for CLI interactions.
• Monitor session lifecycle to prevent memory leaks.

For Users

• Start with default settings for optimal experience.
• Use sessions for complex tasks requiring multiple interactions.
• Choose reasoning effort wisely to balance speed and quality.
• Keep CLI updated for latest features and bug fixes.

To use the Codex MCP Server, ensure your environment meets these requirements:

1. Codex CLI Version: Must be 0.36.0 or later.
2. Authentication: Log in using your API key via the CLI.
3. Verification: Run codex --help to ensure the CLI is installed and functional.

codex login --api-key "your-key"
codex --help

To add the Codex MCP Server to your Claude Code environment, use the claude mcp add command with npx.

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

To use the Codex MCP Server with Claude Desktop, add the following configuration to your claude_desktop_config.json file.

File Locations:

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