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

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, 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 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), 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:

codex mcp list

For scripting and automation, output as JSON:

codex mcp list --json

Adding Local Stdio Servers

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

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:

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:

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

Remove stored credentials:

codex mcp logout remote-api

Inspecting and Removing Servers

View detailed configuration for a specific server:

codex mcp get my-tool --json

Remove a server entry:

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	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	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	Manages live connections to MCP servers, handling stdio process spawning and HTTP stream maintenance.
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	Handles MCP resource requests for accessing external data sources.
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	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.
• 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.

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