MCP CLI Commands

Relevant source files

This page documents the codex mcp subcommands that allow users to manage Model Context Protocol (MCP) server configurations from the command line. These commands provide a convenient interface for adding, removing, listing, and authenticating with MCP servers without manually editing configuration files.

For information about the MCP server configuration structure and connection lifecycle, see MCP Server Configuration and MCP Connection Manager. For details on OAuth implementation, see OAuth Authentication for MCP.

Command Overview

The MCP CLI commands are implemented as subcommands under codex mcp. All commands operate on the global MCP server configuration stored in ~/.codex/config.toml (or $CODEX_HOME/config.toml).

Available Commands:

list — Display all configured MCP servers with their status
get <name> — Show detailed configuration for a specific server
add <name> — Add a new MCP server configuration
remove <name> — Delete an MCP server configuration
login <name> — Authenticate with an MCP server via OAuth
logout <name> — Remove stored OAuth credentials

Sources: codex-rs/cli/src/mcp_cmd.rs23-47

Command Dispatch Architecture

Diagram: MCP Command Dispatch Flow

The McpCli struct serves as the entry point, delegating to dedicated handler functions for each subcommand. Read operations (list, get) load the full Config to access merged configuration from all layers, while write operations (add, remove) directly manipulate the global MCP servers map via ConfigEditsBuilder.

Sources: codex-rs/cli/src/mcp_cmd.rs30-37 codex-rs/cli/src/mcp_cmd.rs151-180

List Command

The list command displays all configured MCP servers. It supports both human-readable table output and JSON format via the --json flag.

Usage

Human-Readable Output

The command groups servers by transport type (stdio vs streamable-http) and displays them in separate tables:

Stdio Servers Table:

Column	Description
Name	Server identifier
Command	Executable or script path
Args	Command-line arguments
Env	Environment variables (inline and from `env_vars`)
Cwd	Working directory
Status	`enabled` or `disabled: <reason>`
Auth	OAuth status: `authenticated`, `unauthenticated`, `unsupported`

Streamable HTTP Servers Table:

Column	Description
Name	Server identifier
Url	HTTP endpoint URL
Bearer Token Env Var	Environment variable containing token
Status	`enabled` or `disabled: <reason>`
Auth	OAuth status

Environment variables are displayed with their values masked (e.g., TOKEN=*****) for security. Variables listed in env_vars are shown as VAR_NAME=***** even if not set, indicating they will be propagated from the parent environment if available.

Sources: codex-rs/cli/src/mcp_cmd.rs395-643 codex-rs/cli/tests/mcp_list.rs20-139

JSON Output

With --json, the command outputs an array of server configurations with full details:

Sources: codex-rs/cli/src/mcp_cmd.rs411-468

Authentication Status Computation

The list command calls compute_auth_statuses() to determine OAuth status for each server. This function:

Checks if the transport supports OAuth (streamable-http only)
Attempts to load stored credentials from the configured store mode
Returns McpAuthStatus:
- Authenticated — Valid credentials exist
- Unauthenticated — OAuth supported but no credentials
- Unsupported — Transport doesn't support OAuth (stdio)

Sources: codex-rs/cli/src/mcp_cmd.rs405-409

Get Command

The get command displays detailed configuration for a single MCP server.

Usage

Human-Readable Output

For enabled servers, get displays a detailed breakdown:

docs
  enabled: true
  enabled_tools: tool1, tool2
  disabled_tools: tool3
  transport: stdio
  command: docs-server
  args: --port 4000
  cwd: /path/to/workspace
  env: TOKEN=*****, APP_TOKEN=*****
  startup_timeout_sec: 10.0
  tool_timeout_sec: 60.0
  remove: codex mcp remove docs

For disabled servers, it shows a single line with the reason:

docs (disabled: org policy)

Sources: codex-rs/cli/src/mcp_cmd.rs645-802

JSON Output

The JSON format mirrors the structure in the list command but for a single server. Environment variables and headers are shown with their actual values (not masked) in JSON output.

Sources: codex-rs/cli/src/mcp_cmd.rs657-701

Add Command

The add command creates a new MCP server configuration. It supports two transport types: stdio (for local executables) and streamable-http (for remote HTTP servers).

Usage

Stdio transport:

Streamable HTTP transport:

Command Arguments

The AddArgs struct defines the argument structure:

Argument	Type	Description
`name`	String	Server identifier (must match `^[a-zA-Z0-9_-]+$`)
`--env`	KEY=VALUE pairs	Environment variables for stdio servers
`command`	Trailing args	Executable and arguments after `--`
`--url`	String	HTTP endpoint for streamable-http servers
`--bearer-token-env-var`	String	Environment variable containing auth token

The command uses ArgGroup to ensure exactly one transport type is specified.

Sources: codex-rs/cli/src/mcp_cmd.rs66-127

Add Flow

Diagram: Add Command Execution Flow

Sources: codex-rs/cli/src/mcp_cmd.rs183-287

OAuth Auto-Detection

After adding a streamable-http server, the add command automatically checks for OAuth support:

Calls oauth_login_support() to probe the server's /oauth/start endpoint
If OAuth is supported, immediately initiates perform_oauth_login()
If support is unknown, prints a hint: "Run codex mcp login <name> to login"

This eliminates the need for a separate login step in most cases.

Sources: codex-rs/cli/src/mcp_cmd.rs265-284

Server Name Validation

Server names must conform to ^[a-zA-Z0-9_-]+$. The validate_server_name() function enforces this to ensure:

No conflicts with TOML syntax
Names are filesystem-safe
Compatibility with the qualified tool name format (mcp__<server>__<tool>)

Sources: codex-rs/cli/src/mcp_cmd.rs819-830

Environment Variable Handling

The add command supports two ways to pass environment variables to stdio servers:

Inline env map (--env KEY=VALUE): Values are stored directly in the config file
env_vars whitelist: Not configurable via CLI (requires manual TOML editing); propagates parent process environment variables

The --env flag uses parse_env_pair() to split KEY=VALUE strings, validating that both parts are non-empty.

Sources: codex-rs/cli/src/mcp_cmd.rs204-223 codex-rs/cli/src/mcp_cmd.rs804-816

Remove Command

The remove command deletes an MCP server configuration from the global config file.

Usage

Behavior

Validates the server name format
Loads the current mcp_servers map from ~/.codex/config.toml
Removes the entry if it exists
Writes the updated map back via ConfigEditsBuilder
Prints confirmation or "not found" message

If the server doesn't exist, the command succeeds with a message rather than failing. This makes remove idempotent.

Sources: codex-rs/cli/src/mcp_cmd.rs289-320

Note: Removing a server does not delete stored OAuth credentials. Use codex mcp logout <name> first to clean up credentials.

The login command authenticates with an MCP server using OAuth 2.0. It only works with streamable-http servers that expose OAuth endpoints.

Usage

Diagram: OAuth Login Command Flow

Sources: codex-rs/cli/src/mcp_cmd.rs322-363

Scope Specification

OAuth scopes can be specified in two ways:

Command-line flag: --scopes read:repos,write:issues (comma-separated)
Config file: scopes = ["read:repos", "write:issues"] in the server entry

If --scopes is provided, it overrides the config. If neither is set, an empty scope list is used (server-dependent default).

Sources: codex-rs/cli/src/mcp_cmd.rs346-349

Callback Server

The perform_oauth_login() function (from codex-rmcp-client) spawns a temporary HTTP server to receive the OAuth callback:

Binds to {bind_host}:{port} where:
- bind_host is 127.0.0.1 for localhost callbacks, 0.0.0.0 for external callbacks
- port is from mcp_oauth_callback_port config (default: random available port via :0)
Constructs redirect_uri from mcp_oauth_callback_url config or defaults to http://127.0.0.1:{port}/callback
Calls OAuthState::start_authorization() with scopes and redirect URI
Opens browser to the authorization URL returned by the OAuth server
HTTP server awaits callback at the configured path (e.g., /callback)
Exchanges authorization code for access/refresh tokens via OAuthState::handle_callback()
Stores tokens according to mcp_oauth_credentials_store_mode

The callback server uses tiny_http::Server and runs in a blocking thread spawned by spawn_callback_server(). The OAuth flow uses the rmcp crate's OAuthState state machine to manage the authorization process.

Sources: codex-rs/rmcp-client/src/perform_oauth_login.rs298-358 codex-rs/rmcp-client/src/perform_oauth_login.rs108-146 codex-rs/cli/src/mcp_cmd.rs351-361

Logout Command

The logout command removes stored OAuth credentials for an MCP server.

Usage

Behavior

Loads the config to verify the server exists
Checks that the server uses streamable_http transport
Calls delete_oauth_tokens() to remove credentials from storage
Prints success or "not found" message

The function returns Ok(true) if credentials existed and were deleted, Ok(false) if no credentials were found. Both cases are treated as success.

Sources: codex-rs/cli/src/mcp_cmd.rs365-393

Storage Locations:

File mode: ~/.codex/.credentials/{server_name}.json
Keychain mode: Platform keychain (Keychain on macOS, Windows Credential Manager, Secret Service on Linux)

The storage mode is controlled by the mcp_oauth_credentials_store_mode config option.

Sources: codex-rs/cli/src/mcp_cmd.rs386

Configuration Persistence

All write operations (add, remove) use the ConfigEditsBuilder API to safely modify the global configuration file.

Edit Process

Diagram: Configuration Update Pipeline

The ConfigEditsBuilder::replace_mcp_servers() method:

Serializes the mcp_servers map to TOML
Parses the existing config file
Replaces the [mcp_servers] table
Writes atomically (temp file + rename)

This ensures that concurrent edits or parse errors don't corrupt the config.

Sources: codex-rs/cli/src/mcp_cmd.rs257-261 codex-rs/cli/src/mcp_cmd.rs306-310

Server Configuration Structure

Each server entry is a McpServerConfig:

Field	Type	Description
`transport`	`McpServerTransportConfig`	stdio or streamable_http details
`enabled`	`bool`	Whether to load server on startup
`required`	`bool`	Session fails if startup fails
`disabled_reason`	`Option<String>`	Human-readable disable reason
`startup_timeout_sec`	`Option<Duration>`	Override default 10s timeout
`tool_timeout_sec`	`Option<Duration>`	Override default 60s timeout
`enabled_tools`	`Option<Vec<String>>`	Allowlist (none = all allowed)
`disabled_tools`	`Option<Vec<String>>`	Blocklist
`scopes`	`Option<Vec<String>>`	Default OAuth scopes

Sources: codex-rs/cli/src/mcp_cmd.rs243-253

OAuth Credential Storage Modes

The mcp_oauth_credentials_store_mode config option controls where OAuth tokens are persisted. The implementation is in codex-rmcp-client crate.

Storage Mode Enum

The Auto mode (default) attempts to use the platform keyring and falls back to file storage if the keyring is unavailable or returns an error. The Keyring mode fails immediately if keyring access is not available.

Sources: codex-rs/rmcp-client/src/oauth.rs67-79

File Storage

Location: $CODEX_HOME/.credentials/{server_key}.json

The server_key is computed as sha256(server_name + url) to create a unique identifier for each server configuration.

Format (StoredOAuthTokens struct):

Permissions: The file is created with 0600 (owner read/write only) for security.

Sources: codex-rs/rmcp-client/src/oauth.rs56-64 codex-rs/rmcp-client/src/oauth.rs285-289

Keychain Storage

Uses platform-specific secure storage via the keyring crate:

macOS: Keychain Access (via security framework, apple-native feature)
Windows: Windows Credential Manager (via wincred API, windows-native feature)
Linux: DBus Secret Service + kernel keyutils (via linux-native-async-persistent feature)

Service name: Codex MCP Credentials (constant KEYRING_SERVICE) Account name: {server_key} (computed from server name + URL) Password: JSON-serialized StoredOAuthTokens object

The keyring store operations are implemented in codex-keyring-store crate, which wraps the keyring crate with async support.

Sources: codex-rs/rmcp-client/src/oauth.rs53 codex-rs/rmcp-client/src/oauth.rs152-168 codex-rs/rmcp-client/Cargo.toml63-74

Default Mode and Fallback

The default mode is Auto, which provides the best security (keyring) when available while ensuring the CLI remains functional on systems where keyring access fails. The fallback chain is:

Keyring write: If successful, also deletes any existing file storage for the same server
File write: If keyring fails, stores credentials in ~/.codex/.credentials/{server_key}.json

During reads, Auto mode first checks the keyring, then falls back to file storage if keyring access fails.

Sources: codex-rs/rmcp-client/src/oauth.rs136-150 codex-rs/rmcp-client/src/oauth.rs215-229

Error Handling

Common Error Cases

Error	Command	Cause
"invalid server name"	`add`, `remove`, `login`, `logout`	Name contains invalid characters
"No MCP server named 'X' found"	`get`, `login`, `logout`	Server not in config
"OAuth login is only supported for streamable HTTP servers"	`login`	Attempted OAuth with stdio server
"Environment variable {var} for MCP server '{name}' is not set"	Runtime (not CLI)	Missing required env var
"exactly one of --command or --url must be provided"	`add`	Missing or conflicting transport args

Sources: codex-rs/cli/src/mcp_cmd.rs819-830 codex-rs/cli/src/mcp_cmd.rs332-344

Config Override Validation

All commands validate CliConfigOverrides (from --config-file or -c flags) before executing. This ensures that any user-provided overrides are syntactically valid, even though they're not applied during MCP command execution.

Sources: codex-rs/cli/src/mcp_cmd.rs185-190

Command Output Formatting

Table Rendering

The list command uses a simple ASCII table format with dynamically calculated column widths:

Compute max width for each column across all rows
Print header row with padding
Print data rows with consistent spacing

Sensitive values (environment variables, tokens) are masked with ***** in human-readable output but shown in full in JSON mode.

Sources: codex-rs/cli/src/mcp_cmd.rs538-640

Environment Display

The format_env_display() utility (from codex_utils_cli) combines inline env and env_vars into a single display string:

TOKEN=*****, APP_TOKEN=*****, WORKSPACE_ID=*****

If both are empty, displays - for clarity.

Sources: codex-rs/cli/src/mcp_cmd.rs492 codex-rs/cli/src/mcp_cmd.rs752

Testing

The MCP CLI commands have comprehensive integration tests that verify:

Add/Remove cycle: Server is added to config, then removed
List output: Both human-readable and JSON formats match expected structure
Get output: Detailed display shows all fields correctly
Environment handling: Inline env and env_vars are parsed and displayed
Disabled servers: Single-line output for disabled entries
Streamable HTTP: URL and bearer token fields are handled correctly

Tests use tempfile::TempDir to isolate $CODEX_HOME and avoid polluting the user's real config.

Sources: codex-rs/cli/tests/mcp_list.rs codex-rs/cli/tests/mcp_add_remove.rs

MCP CLI Commands

Relevant source files

Command Overview

The MCP CLI commands are implemented as subcommands under codex mcp. All commands operate on the global MCP server configuration stored in ~/.codex/config.toml (or $CODEX_HOME/config.toml).

Available Commands:

list — Display all configured MCP servers with their status
get <name> — Show detailed configuration for a specific server
add <name> — Add a new MCP server configuration
remove <name> — Delete an MCP server configuration
login <name> — Authenticate with an MCP server via OAuth
logout <name> — Remove stored OAuth credentials

Sources: codex-rs/cli/src/mcp_cmd.rs23-47

Command Dispatch Architecture

Diagram: MCP Command Dispatch Flow

Sources: codex-rs/cli/src/mcp_cmd.rs30-37 codex-rs/cli/src/mcp_cmd.rs151-180

List Command

The list command displays all configured MCP servers. It supports both human-readable table output and JSON format via the --json flag.

Usage

Human-Readable Output

The command groups servers by transport type (stdio vs streamable-http) and displays them in separate tables:

Stdio Servers Table:

Column	Description
Name	Server identifier
Command	Executable or script path
Args	Command-line arguments
Env	Environment variables (inline and from `env_vars`)
Cwd	Working directory
Status	`enabled` or `disabled: <reason>`
Auth	OAuth status: `authenticated`, `unauthenticated`, `unsupported`

Streamable HTTP Servers Table:

Column	Description
Name	Server identifier
Url	HTTP endpoint URL
Bearer Token Env Var	Environment variable containing token
Status	`enabled` or `disabled: <reason>`
Auth	OAuth status

Sources: codex-rs/cli/src/mcp_cmd.rs395-643 codex-rs/cli/tests/mcp_list.rs20-139

JSON Output

With --json, the command outputs an array of server configurations with full details:

Sources: codex-rs/cli/src/mcp_cmd.rs411-468

Authentication Status Computation

The list command calls compute_auth_statuses() to determine OAuth status for each server. This function:

Checks if the transport supports OAuth (streamable-http only)
Attempts to load stored credentials from the configured store mode
Returns McpAuthStatus:
- Authenticated — Valid credentials exist
- Unauthenticated — OAuth supported but no credentials
- Unsupported — Transport doesn't support OAuth (stdio)

Sources: codex-rs/cli/src/mcp_cmd.rs405-409

Get Command

The get command displays detailed configuration for a single MCP server.

Usage

Human-Readable Output

For enabled servers, get displays a detailed breakdown:

docs
  enabled: true
  enabled_tools: tool1, tool2
  disabled_tools: tool3
  transport: stdio
  command: docs-server
  args: --port 4000
  cwd: /path/to/workspace
  env: TOKEN=*****, APP_TOKEN=*****
  startup_timeout_sec: 10.0
  tool_timeout_sec: 60.0
  remove: codex mcp remove docs

For disabled servers, it shows a single line with the reason:

docs (disabled: org policy)

Sources: codex-rs/cli/src/mcp_cmd.rs645-802

JSON Output

The JSON format mirrors the structure in the list command but for a single server. Environment variables and headers are shown with their actual values (not masked) in JSON output.

Sources: codex-rs/cli/src/mcp_cmd.rs657-701

Add Command

The add command creates a new MCP server configuration. It supports two transport types: stdio (for local executables) and streamable-http (for remote HTTP servers).

Usage

Stdio transport:

Streamable HTTP transport:

Command Arguments

The AddArgs struct defines the argument structure:

Argument	Type	Description
`name`	String	Server identifier (must match `^[a-zA-Z0-9_-]+$`)
`--env`	KEY=VALUE pairs	Environment variables for stdio servers
`command`	Trailing args	Executable and arguments after `--`
`--url`	String	HTTP endpoint for streamable-http servers
`--bearer-token-env-var`	String	Environment variable containing auth token

The command uses ArgGroup to ensure exactly one transport type is specified.

Sources: codex-rs/cli/src/mcp_cmd.rs66-127

Add Flow

Diagram: Add Command Execution Flow

Sources: codex-rs/cli/src/mcp_cmd.rs183-287

OAuth Auto-Detection

After adding a streamable-http server, the add command automatically checks for OAuth support:

Calls oauth_login_support() to probe the server's /oauth/start endpoint
If OAuth is supported, immediately initiates perform_oauth_login()
If support is unknown, prints a hint: "Run codex mcp login <name> to login"

This eliminates the need for a separate login step in most cases.

Sources: codex-rs/cli/src/mcp_cmd.rs265-284

Server Name Validation

Server names must conform to ^[a-zA-Z0-9_-]+$. The validate_server_name() function enforces this to ensure:

No conflicts with TOML syntax
Names are filesystem-safe
Compatibility with the qualified tool name format (mcp__<server>__<tool>)

Sources: codex-rs/cli/src/mcp_cmd.rs819-830

Environment Variable Handling

The add command supports two ways to pass environment variables to stdio servers:

Inline env map (--env KEY=VALUE): Values are stored directly in the config file
env_vars whitelist: Not configurable via CLI (requires manual TOML editing); propagates parent process environment variables

The --env flag uses parse_env_pair() to split KEY=VALUE strings, validating that both parts are non-empty.

Sources: codex-rs/cli/src/mcp_cmd.rs204-223 codex-rs/cli/src/mcp_cmd.rs804-816

Remove Command

The remove command deletes an MCP server configuration from the global config file.

Usage

Behavior

Validates the server name format
Loads the current mcp_servers map from ~/.codex/config.toml
Removes the entry if it exists
Writes the updated map back via ConfigEditsBuilder
Prints confirmation or "not found" message

If the server doesn't exist, the command succeeds with a message rather than failing. This makes remove idempotent.

Sources: codex-rs/cli/src/mcp_cmd.rs289-320

Note: Removing a server does not delete stored OAuth credentials. Use codex mcp logout <name> first to clean up credentials.

The login command authenticates with an MCP server using OAuth 2.0. It only works with streamable-http servers that expose OAuth endpoints.

Usage

Diagram: OAuth Login Command Flow

Sources: codex-rs/cli/src/mcp_cmd.rs322-363

Scope Specification

OAuth scopes can be specified in two ways:

Command-line flag: --scopes read:repos,write:issues (comma-separated)
Config file: scopes = ["read:repos", "write:issues"] in the server entry

If --scopes is provided, it overrides the config. If neither is set, an empty scope list is used (server-dependent default).

Sources: codex-rs/cli/src/mcp_cmd.rs346-349

Callback Server

The perform_oauth_login() function (from codex-rmcp-client) spawns a temporary HTTP server to receive the OAuth callback:

Binds to {bind_host}:{port} where:
- bind_host is 127.0.0.1 for localhost callbacks, 0.0.0.0 for external callbacks
- port is from mcp_oauth_callback_port config (default: random available port via :0)
Constructs redirect_uri from mcp_oauth_callback_url config or defaults to http://127.0.0.1:{port}/callback
Calls OAuthState::start_authorization() with scopes and redirect URI
Opens browser to the authorization URL returned by the OAuth server
HTTP server awaits callback at the configured path (e.g., /callback)
Exchanges authorization code for access/refresh tokens via OAuthState::handle_callback()
Stores tokens according to mcp_oauth_credentials_store_mode

Sources: codex-rs/rmcp-client/src/perform_oauth_login.rs298-358 codex-rs/rmcp-client/src/perform_oauth_login.rs108-146 codex-rs/cli/src/mcp_cmd.rs351-361

Logout Command

The logout command removes stored OAuth credentials for an MCP server.

Usage

Behavior

Loads the config to verify the server exists
Checks that the server uses streamable_http transport
Calls delete_oauth_tokens() to remove credentials from storage
Prints success or "not found" message

The function returns Ok(true) if credentials existed and were deleted, Ok(false) if no credentials were found. Both cases are treated as success.

Sources: codex-rs/cli/src/mcp_cmd.rs365-393

Storage Locations:

File mode: ~/.codex/.credentials/{server_name}.json
Keychain mode: Platform keychain (Keychain on macOS, Windows Credential Manager, Secret Service on Linux)

The storage mode is controlled by the mcp_oauth_credentials_store_mode config option.

Sources: codex-rs/cli/src/mcp_cmd.rs386

Configuration Persistence

All write operations (add, remove) use the ConfigEditsBuilder API to safely modify the global configuration file.

Edit Process

Diagram: Configuration Update Pipeline

The ConfigEditsBuilder::replace_mcp_servers() method:

Serializes the mcp_servers map to TOML
Parses the existing config file
Replaces the [mcp_servers] table
Writes atomically (temp file + rename)

This ensures that concurrent edits or parse errors don't corrupt the config.

Sources: codex-rs/cli/src/mcp_cmd.rs257-261 codex-rs/cli/src/mcp_cmd.rs306-310

Server Configuration Structure

Each server entry is a McpServerConfig:

Field	Type	Description
`transport`	`McpServerTransportConfig`	stdio or streamable_http details
`enabled`	`bool`	Whether to load server on startup
`required`	`bool`	Session fails if startup fails
`disabled_reason`	`Option<String>`	Human-readable disable reason
`startup_timeout_sec`	`Option<Duration>`	Override default 10s timeout
`tool_timeout_sec`	`Option<Duration>`	Override default 60s timeout
`enabled_tools`	`Option<Vec<String>>`	Allowlist (none = all allowed)
`disabled_tools`	`Option<Vec<String>>`	Blocklist
`scopes`	`Option<Vec<String>>`	Default OAuth scopes

Sources: codex-rs/cli/src/mcp_cmd.rs243-253

OAuth Credential Storage Modes

The mcp_oauth_credentials_store_mode config option controls where OAuth tokens are persisted. The implementation is in codex-rmcp-client crate.

Storage Mode Enum

Sources: codex-rs/rmcp-client/src/oauth.rs67-79

File Storage

Location: $CODEX_HOME/.credentials/{server_key}.json

The server_key is computed as sha256(server_name + url) to create a unique identifier for each server configuration.

Format (StoredOAuthTokens struct):

Permissions: The file is created with 0600 (owner read/write only) for security.

Sources: codex-rs/rmcp-client/src/oauth.rs56-64 codex-rs/rmcp-client/src/oauth.rs285-289

Keychain Storage

Uses platform-specific secure storage via the keyring crate:

macOS: Keychain Access (via security framework, apple-native feature)
Windows: Windows Credential Manager (via wincred API, windows-native feature)
Linux: DBus Secret Service + kernel keyutils (via linux-native-async-persistent feature)

Service name: Codex MCP Credentials (constant KEYRING_SERVICE) Account name: {server_key} (computed from server name + URL) Password: JSON-serialized StoredOAuthTokens object

The keyring store operations are implemented in codex-keyring-store crate, which wraps the keyring crate with async support.

Sources: codex-rs/rmcp-client/src/oauth.rs53 codex-rs/rmcp-client/src/oauth.rs152-168 codex-rs/rmcp-client/Cargo.toml63-74

Default Mode and Fallback

The default mode is Auto, which provides the best security (keyring) when available while ensuring the CLI remains functional on systems where keyring access fails. The fallback chain is:

Keyring write: If successful, also deletes any existing file storage for the same server
File write: If keyring fails, stores credentials in ~/.codex/.credentials/{server_key}.json

During reads, Auto mode first checks the keyring, then falls back to file storage if keyring access fails.

Sources: codex-rs/rmcp-client/src/oauth.rs136-150 codex-rs/rmcp-client/src/oauth.rs215-229

Error Handling

Common Error Cases

Error	Command	Cause
"invalid server name"	`add`, `remove`, `login`, `logout`	Name contains invalid characters
"No MCP server named 'X' found"	`get`, `login`, `logout`	Server not in config
"OAuth login is only supported for streamable HTTP servers"	`login`	Attempted OAuth with stdio server
"Environment variable {var} for MCP server '{name}' is not set"	Runtime (not CLI)	Missing required env var
"exactly one of --command or --url must be provided"	`add`	Missing or conflicting transport args

Sources: codex-rs/cli/src/mcp_cmd.rs819-830 codex-rs/cli/src/mcp_cmd.rs332-344

Config Override Validation

Sources: codex-rs/cli/src/mcp_cmd.rs185-190

Command Output Formatting

Table Rendering

The list command uses a simple ASCII table format with dynamically calculated column widths:

Compute max width for each column across all rows
Print header row with padding
Print data rows with consistent spacing

Sensitive values (environment variables, tokens) are masked with ***** in human-readable output but shown in full in JSON mode.

Sources: codex-rs/cli/src/mcp_cmd.rs538-640

Environment Display

The format_env_display() utility (from codex_utils_cli) combines inline env and env_vars into a single display string:

TOKEN=*****, APP_TOKEN=*****, WORKSPACE_ID=*****

If both are empty, displays - for clarity.

Sources: codex-rs/cli/src/mcp_cmd.rs492 codex-rs/cli/src/mcp_cmd.rs752

Testing

The MCP CLI commands have comprehensive integration tests that verify:

Add/Remove cycle: Server is added to config, then removed
List output: Both human-readable and JSON formats match expected structure
Get output: Detailed display shows all fields correctly
Environment handling: Inline env and env_vars are parsed and displayed
Disabled servers: Single-line output for disabled entries
Streamable HTTP: URL and bearer token fields are handled correctly

Tests use tempfile::TempDir to isolate $CODEX_HOME and avoid polluting the user's real config.

Sources: codex-rs/cli/tests/mcp_list.rs codex-rs/cli/tests/mcp_add_remove.rs

MCP CLI Commands

Command Overview

Command Dispatch Architecture

List Command

Usage

Human-Readable Output

JSON Output

Authentication Status Computation

Get Command

Usage

Human-Readable Output

JSON Output

Add Command

Usage

Command Arguments

Add Flow

OAuth Auto-Detection

Server Name Validation

Environment Variable Handling

Remove Command

Usage

Behavior

Login Command

Usage

Login Flow

Scope Specification

Callback Server

Logout Command

Usage

Behavior

Configuration Persistence

Edit Process

Server Configuration Structure

OAuth Credential Storage Modes

Storage Mode Enum

File Storage

Keychain Storage

Default Mode and Fallback

Error Handling

Common Error Cases

Config Override Validation

Command Output Formatting

Table Rendering

Environment Display

Testing

On this page

MCP CLI Commands

Command Overview

Command Dispatch Architecture

List Command

Usage

Human-Readable Output

JSON Output

Authentication Status Computation

Get Command

Usage

Human-Readable Output

JSON Output

Add Command

Usage

Command Arguments

Add Flow

OAuth Auto-Detection

Server Name Validation

Environment Variable Handling

Remove Command

Usage

Behavior

Login Command

Usage

Login Flow

Scope Specification

Callback Server

Logout Command

Usage

Behavior

Configuration Persistence

Edit Process

Server Configuration Structure

OAuth Credential Storage Modes