How to Start Codex CLI as an MCP Server: A Complete Configuration Guide

Run codex mcp-server to start the OpenAI Codex CLI as a Model Context Protocol (MCP) server, exposing a JSON-RPC API over stdin/stdout for programmatic integration.

The OpenAI Codex CLI can operate as a standalone Model Context Protocol (MCP) server, enabling external tools to invoke its code intelligence capabilities via a structured JSON-RPC interface. This configuration transforms the interactive CLI into a programmatic backend that handles threads, turns, and model interactions over standard input/output streams. When you start Codex CLI as an MCP server, the binary initializes an rmcp::Client configured for stdio transport and begins listening for v2 protocol commands defined in the app-server protocol crate.

What Is the Codex MCP Server?

The Codex MCP server implements the Model Context Protocol, a JSON-RPC based standard for exposing AI tool capabilities to external clients. When running in this mode, Codex exposes methods for managing conversation threads, executing turns, handling user approvals, and streaming notifications.

Key architectural components include:

• codex-rs/mcp-server/src/main.rs – The entry point that launches the MCP listener and boots the app-server core.
• codex-rs/mcp-server/src/message_processor.rs – Parses incoming JSON-RPC requests, dispatches them to the app-server, and writes responses.
• codex-rs/rmcp-client/src/rmcp_client.rs – Low-level MCP transport implementation handling stdio streams.
• app-server-protocol/src/protocol/v2.rs – Defines all v2 RPC methods, request/response shapes, and typed notifications.

Starting Codex CLI as an MCP Server

Basic Launch via Command Line

The simplest method to start the server is invoking the mcp-server subcommand. This starts the JSON-RPC listener on stdin/stdout:

codex mcp-server

You can then pipe this to any MCP-compatible client or connect via the stdio transport directly.

Using the MCP Inspector for Testing

For interactive debugging and manual testing, use the official MCP inspector tool. This launches a web interface that connects to your Codex MCP server:

npx @modelcontextprotocol/inspector codex mcp-server

The inspector

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}