MCP Server Implementation (codex-mcp-server)

Relevant source files

• codex-rs/exec/src/main.rs
• codex-rs/mcp-server/Cargo.toml
• codex-rs/mcp-server/src/codex_tool_config.rs
• codex-rs/mcp-server/src/lib.rs
• codex-rs/mcp-server/src/main.rs
• codex-rs/mcp-server/src/message_processor.rs
• codex-rs/mcp-server/src/outgoing_message.rs
• codex-rs/mcp-server/tests/common/mcp_process.rs
• codex-rs/mcp-server/tests/suite/mod.rs
• codex-rs/tui/src/main.rs

Purpose and Scope

This document describes the codex-mcp-server implementation, which exposes Codex as an MCP (Model Context Protocol) server. This allows external MCP clients—such as Claude Desktop, Zed Editor, or custom applications—to invoke Codex as a tool over stdio JSON-RPC. The server provides the codex tool for starting and continuing conversations, managing the underlying agent sessions via ThreadManager. codex-rs/mcp-server/src/lib.rs1-13

CLI Entry Point: The server is typically launched via the codex mcp-server subcommand. The binary uses arg0_dispatch_or_else to handle its execution logic, ensuring proper binary path resolution for sandboxing and utility dispatch. codex-rs/mcp-server/src/main.rs8-18 codex-rs/mcp-server/src/lib.rs60-64

For information about Codex acting as an MCP client to consume external MCP tools, see pages 6.1 (MCP Server Configuration) and 6.2 (MCP Connection Manager).

Sources: codex-rs/mcp-server/src/lib.rs1-13 codex-rs/mcp-server/src/main.rs8-18 codex-rs/mcp-server/Cargo.toml7-13

Overview

The codex-mcp-server crate implements a JSON-RPC server that communicates over stdio, following the Model Context Protocol specification. When an MCP client invokes the codex tool, the server spawns a Codex session using ThreadManager from codex-core, streams events back to the client as notifications, and returns the final response when the turn completes. codex-rs/mcp-server/src/message_processor.rs81-96 codex-rs/mcp-server/src/message_processor.rs141-143

Key characteristics:

• Transport: stdio JSON-RPC (line-delimited JSON messages). codex-rs/mcp-server/src/lib.rs128-148 codex-rs/mcp-server/src/lib.rs177-197
• Tools exposed: codex (managed via CodexToolCallParam) and codex_reply (managed via CodexToolCallReplyParam). codex-rs/mcp-server/src/message_processor.rs35-38 codex-rs/mcp-server/src/message_processor.rs138-143
• Event streaming: Codex Event types are translated to codex/event notifications. codex-rs/mcp-server/src/outgoing_message.rs102-125
• Session multiplexing: Multiple threads can share a single MCP connection via threadId mapping in the processor. codex-rs/mcp-server/src/message_processor.rs46-47 codex-rs/mcp-server/src/message_processor.rs102
• Environment Integration: Integrates with EnvironmentManager for capability root resolution and execution. codex-rs/mcp-server/src/message_processor.rs56 codex-rs/mcp-server/src/lib.rs97-108

Sources: codex-rs/mcp-server/src/lib.rs1-197 codex-rs/mcp-server/src/message_processor.rs41-96 codex-rs/mcp-server/src/outgoing_message.rs102-125

System Architecture

Component Diagram (Code Entity Space)

This diagram shows how the MCP server components interact with the core Codex systems.

Sources: codex-rs/mcp-server/src/lib.rs60-185 codex-rs/mcp-server/src/message_processor.rs41-98 codex-rs/mcp-server/src/outgoing_message.rs27-40

Message Flow (Natural Language to Code Space)

This diagram illustrates the flow of a tool call from the client into the Codex execution engine.

Sources: codex-rs/mcp-server/src/message_processor.rs106-180 codex-rs/mcp-server/src/outgoing_message.rs42-136 codex-rs/mcp-server/src/lib.rs128-185

Tool Definitions

The server exposes Codex capabilities as MCP tools. The primary tools are codex for initiating tasks and codex_reply for continuing conversations. codex-rs/mcp-server/src/message_processor.rs138-143

Tool: codex

Input Schema Fields (CodexToolCallParam):

Field	Type	Description
prompt	string	Initial user prompt to start the conversation. codex-rs/mcp-server/src/codex_tool_config.rs27
model	string	Model name override (e.g., gpt-4o). codex-rs/mcp-server/src/codex_tool_config.rs31
cwd	string	Working directory for the session. codex-rs/mcp-server/src/codex_tool_config.rs36
approval-policy	string	Approval policy for shell commands (untrusted, on-request, never). codex-rs/mcp-server/src/codex_tool_config.rs41
sandbox	string	Sandbox mode (read-only, workspace-write, danger-full-access). codex-rs/mcp-server/src/codex_tool_config.rs45
config	map	Key-value overrides for config.toml. codex-rs/mcp-server/src/codex_tool_config.rs50

Output Schema: The tool returns a CallToolResult containing the conversation content and the associated threadId. codex-rs/mcp-server/src/message_processor.rs18 codex-rs/mcp-server/src/codex_tool_config.rs126-134

Sources: codex-rs/mcp-server/src/codex_tool_config.rs25-63 codex-rs/mcp-server/src/message_processor.rs138-143

Message Processing

MessageProcessor Implementation

The MessageProcessor is the central dispatcher for the server. It is initialized with a ThreadManager configured with SessionSource::Mcp. codex-rs/mcp-server/src/message_processor.rs41-96

Request Handling: The process_request method routes incoming JSON-RPC requests to specific handlers: codex-rs/mcp-server/src/message_processor.rs106-180

• InitializeRequest: Sets up the connection and server capabilities, including ServerCapabilities. codex-rs/mcp-server/src/message_processor.rs111-113 codex-rs/mcp-server/src/message_processor.rs30
• ListToolsRequest: Returns the available tools (codex, codex_reply) using handle_list_tools. codex-rs/mcp-server/src/message_processor.rs138-140
• CallToolRequest: Triggers a Codex turn via handle_call_tool. codex-rs/mcp-server/src/message_processor.rs141-143

Outgoing Message Management

The OutgoingMessageSender handles sending responses, notifications, and requests back to the client. codex-rs/mcp-server/src/outgoing_message.rs27-40

It maintains a request_id_to_callback map to correlate client responses to elicitation requests (like approval requests) sent by the server to the client. codex-rs/mcp-server/src/outgoing_message.rs30-31 codex-rs/mcp-server/src/outgoing_message.rs64-80

Sources: codex-rs/mcp-server/src/message_processor.rs41-180 codex-rs/mcp-server/src/outgoing_message.rs27-136

Task Orchestration

The run_main function sets up three primary async tasks to manage the stdio lifecycle: codex-rs/mcp-server/src/lib.rs60-197

1. Stdin Reader Task: Reads line-delimited JSON from io::stdin, deserializes into IncomingMessage, and sends to the processor channel. codex-rs/mcp-server/src/lib.rs128-148
2. Processor Task: Receives messages from the channel and calls MessageProcessor methods. codex-rs/mcp-server/src/lib.rs151-174
3. Stdout Writer Task: Receives OutgoingMessage from the sender channel, serializes to JSON, and writes to io::stdout. codex-rs/mcp-server/src/lib.rs177-197

Sources: codex-rs/mcp-server/src/lib.rs121-197

Testing

The implementation includes an McpProcess test harness that spawns the server binary and performs the initialization handshake. codex-rs/mcp-server/tests/common/mcp_process.rs35-111

Example Test Workflow:

• initialize(): Validates the protocol handshake and server info, including checking the Implementation details and ProtocolVersion. codex-rs/mcp-server/tests/common/mcp_process.rs114-185 codex-rs/mcp-server/src/message_processor.rs23-24
• Binary Discovery: Tests use codex_utils_cargo_bin::cargo_bin to find the codex-mcp-server executable for integration testing. codex-rs/mcp-server/tests/common/mcp_process.rs60-61

Sources: codex-rs/mcp-server/tests/common/mcp_process.rs35-198