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

> Learn to start Codex CLI as an MCP server. Configure the Model Context Protocol server for programmatic integration via JSON-RPC API over stdin/stdout. Get the complete guide.

- Repository: [OpenAI/codex](https://github.com/openai/codex)
- Tags: how-to-guide
- Published: 2026-03-06

---

**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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/codex-rs/rmcp-client/src/rmcp_client.rs)** – Low-level MCP transport implementation handling stdio streams.
- **[`app-server-protocol/src/protocol/v2.rs`](https://github.com/openai/codex/blob/main/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:

```bash
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:

```bash
npx @modelcontextprotocol/inspector codex mcp-server

```

The inspector