# Codex MCP Subcommand: Configure and Manage Model Context Protocol Servers in OpenAI Codex CLI

> Learn how to use the codex mcp subcommand to configure and manage Model Context Protocol servers for local and remote tools in OpenAI Codex CLI.

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

---

**The `codex mcp` subcommand serves as the configuration and lifecycle manager for Model Context Protocol (MCP) servers, enabling developers to register, authenticate, and manage both local stdio-based tools and remote HTTP endpoints through the `~/.codex/config.toml` file.**

The `codex mcp` subcommand is the primary interface for integrating external tools and resources into the OpenAI Codex CLI using the Model Context Protocol (MCP). Located in the `openai/codex` repository, this subcommand handles everything from server registration and transport configuration to OAuth authentication, allowing Codex to execute tools hosted locally or on remote HTTP endpoints.

## What Is the Codex MCP Subcommand?

The **Model Context Protocol (MCP)** is an open standard that allows AI assistants to discover and invoke external tools, access resources, and maintain context across different environments. The `codex mcp` subcommand acts as the **administrative interface** for this protocol within the Codex CLI.

According to the source code in [`codex-rs/cli/src/mcp_cmd.rs`](https://github.com/openai/codex/blob/main/codex-rs/cli/src/mcp_cmd.rs), the subcommand exposes six primary operations: `list`, `get`, `add`, `remove`, `login`, and `logout`. These operations map to the `McpSubcommand` enum defined at lines 42-50, which serves as the dispatch point for all MCP-related CLI arguments.

## Core Responsibilities and Implementation

### Subcommand Dispatch and CLI Parsing

The CLI parser uses **clap**-derived structs to handle argument validation. The `McpSubcommand` enum in [`codex-rs/cli/src/mcp_cmd.rs`](https://github.com/openai/codex/blob/main/codex-rs/cli/src/mcp_cmd.rs) defines the available commands, while specialized structs like `ListArgs`, `AddArgs`, and `AddMcpTransportArgs` (lines 52-90) handle flag parsing for options such as `--json`, `--url`, and `--bearer-token-env-var`.

### Configuration Management

The subcommand reads and writes the global MCP server configuration stored in **`~/.codex/config.toml`**. The implementation uses `codex_core::config` helpers, specifically `load_global_mcp_servers` and `ConfigEditsBuilder::replace_mcp_servers` (lines 86-106 in [`mcp_cmd.rs`](https://github.com/openai/codex/blob/main/mcp_cmd.rs)), to persist server definitions without corrupting the global configuration state.

### Server Validation and Transport Setup

Before adding a server, the CLI validates the server name using the `validate_server_name` helper function (lines 30-38), which ensures names contain only alphanumeric characters, hyphens, and underscores.

The transport layer is configured through `McpServerTransportConfig` construction inside `run_add` (lines 107-144). The subcommand supports two transport types:
- **Stdio**: Local command-line tools launched as subprocesses
- **Streamable HTTP**: Remote endpoints accessible via URL

### Authentication and OAuth Flows

For HTTP-based MCP servers, the subcommand handles **OAuth 2.0 authentication**. When adding a server with OAuth support (`McpOAuthLoginSupport`), the `run_add` function detects this capability and invokes `perform_oauth_login` (lines 68-86).

Dedicated `login` and `logout` subcommands allow users to manage tokens independently:
- `codex mcp login <server>` triggers `perform_oauth_login` (lines 128-144)
- `codex mcp logout <server>` calls `delete_oauth_tokens` (lines 166-190)

## Available MCP Subcommands

The `codex mcp` command exposes the following operations:

| Command | Purpose | Key Implementation |
|---------|---------|-------------------|
| `list` | Display all configured MCP servers | `run_list` (lines 105-168), uses `McpManager::effective_servers` |
| `get` | Show details for a specific server | `run_get` (lines 154-194) |
| `add` | Register a new stdio or HTTP server | `run_add` (lines 86-144) |
| `remove` | Delete a server configuration | `run_remove` |
| `login` | Authenticate with an HTTP server via OAuth | `run_login` (lines 128-144) |
| `logout` | Remove stored OAuth tokens | `run_logout` (lines 166-190) |

## Practical Examples: Using the Codex MCP Subcommand

### Listing Configured Servers

View all MCP servers in human-readable format:

```bash
codex mcp list

```

For scripting and automation, output as JSON:

```bash
codex mcp list --json

```

### Adding Local Stdio Servers

Register a local command-line tool as an MCP server:

```bash
codex mcp add my-tool -- my-tool-binary --arg1 --arg2

```

The `--` separator distinguishes CLI flags for the Codex command from arguments passed to the target binary.

### Adding Remote HTTP Servers

Configure a streamable HTTP endpoint:

```bash
codex mcp add remote-api --url https://api.example.com/mcp \
    --bearer-token-env-var MCP_TOKEN

```

### Managing OAuth Authentication

Initiate OAuth login for an HTTP server:

```bash
codex mcp login remote-api --scopes openid,email,profile

```

Remove stored credentials:

```bash
codex mcp logout remote-api

```

### Inspecting and Removing Servers

View detailed configuration for a specific server:

```bash
codex mcp get my-tool --json

```

Remove a server entry:

```bash
codex mcp remove my-tool

```

## Key Source Files and Architecture

The `codex mcp` subcommand implementation spans multiple crates in the `openai/codex` repository:

| File | Role |
|------|------|
| [`codex-rs/cli/src/mcp_cmd.rs`](https://github.com/openai/codex/blob/main/codex-rs/cli/src/mcp_cmd.rs) | CLI parser, subcommand dispatcher, and core implementation of `list`, `add`, `remove`, `login`, `logout`, and `get` operations. Contains `McpSubcommand` enum and `validate_server_name` helper. |
| [`codex-rs/core/src/mcp_manager.rs`](https://github.com/openai/codex/blob/main/codex-rs/core/src/mcp_manager.rs) | Computes the effective set of MCP servers by merging global configuration with plugin-provided servers. Used by `run_list` via `McpManager::effective_servers`. |
| [`codex-rs/core/src/mcp_connection_manager.rs`](https://github.com/openai/codex/blob/main/codex-rs/core/src/mcp_connection_manager.rs) | Manages live connections to MCP servers, handling stdio process spawning and HTTP stream maintenance. |
| [`codex-rs/core/src/tools/handlers/mcp.rs`](https://github.com/openai/codex/blob/main/codex-rs/core/src/tools/handlers/mcp.rs) | Backend handler that executes MCP tool calls initiated by the Codex agent. |
| [`codex-rs/core/src/tools/handlers/mcp_resource.rs`](https://github.com/openai/codex/blob/main/codex-rs/core/src/tools/handlers/mcp_resource.rs) | Handles MCP resource requests for accessing external data sources. |
| [`codex-rs/core/src/mcp_tool_call.rs`](https://github.com/openai/codex/blob/main/codex-rs/core/src/mcp_tool_call.rs) | Represents a tool call to an MCP server and processes the response. |
| [`codex-rs/protocol/src/mcp.rs`](https://github.com/openai/codex/blob/main/codex-rs/protocol/src/mcp.rs) | Wire-format definitions for MCP protocol messages (`Tool`, `Resource`, etc.). |

## Summary

- The **`codex mcp` subcommand** is the administrative interface for managing Model Context Protocol (MCP) server integrations in the OpenAI Codex CLI.
- It supports **six primary operations**: `list`, `get`, `add`, `remove`, `login`, and `logout`, implemented in [`codex-rs/cli/src/mcp_cmd.rs`](https://github.com/openai/codex/blob/main/codex-rs/cli/src/mcp_cmd.rs).
- Server configurations are **persisted to `~/.codex/config.toml`** using the `ConfigEditsBuilder` pattern from `codex_core::config`.
- The subcommand handles **two transport types**: local stdio processes and remote streamable HTTP endpoints.
- **OAuth 2.0 authentication** is supported for HTTP servers via dedicated `login` and `logout` commands that manage tokens in the global configuration.

## Frequently Asked Questions

### What does MCP stand for in the Codex CLI?

**MCP** stands for **Model Context Protocol**, an open standard that enables AI assistants to discover and invoke external tools, access resources, and maintain context across different environments. The `codex mcp` subcommand specifically manages connections to MCP servers that expose these capabilities to the Codex agent.

### How do I add a local command-line tool as an MCP server?

Use the `codex mcp add` command with the `--` separator to pass arguments to your binary. For example: `codex mcp add my-tool -- my-tool-binary --arg1 --arg2`. The CLI validates the server name using the `validate_server_name` helper and stores the configuration in `~/.codex/config.toml` as a stdio transport.

### Does the Codex MCP subcommand support authentication for remote servers?

Yes, the subcommand supports **OAuth 2.0 authentication** for HTTP-based MCP servers. When adding a server with `codex mcp add`, you can specify `--bearer-token-env-var` for static tokens. For interactive OAuth flows, use `codex mcp login <server>` to initiate authentication and `codex mcp logout <server>` to remove stored tokens, both implemented in [`codex-rs/cli/src/mcp_cmd.rs`](https://github.com/openai/codex/blob/main/codex-rs/cli/src/mcp_cmd.rs).