This document describes how to configure MCP (Model Context Protocol) servers in Codex. MCP servers extend Codex's capabilities by providing external tools, resources, and data sources that the AI can access during conversations.
For information about how MCP servers are initialized and managed at runtime, see MCP Connection Manager. For CLI commands to manage MCP servers, see MCP CLI Commands. For OAuth authentication flows, see OAuth Authentication for MCP.
MCP servers are configured in config.toml files (system, user, or project level) under the [mcp_servers] section. Each server is identified by a unique name and has a McpServerConfig structure.
| Field | Type | Description |
|---|---|---|
transport | McpServerTransportConfig | Transport configuration (Stdio or StreamableHttp) |
enabled | bool | Whether the server is enabled |
required | bool | If true, Codex fails to start if this server cannot be initialized |
disabled_reason | Option<String> | Optional reason for disabling the server (for documentation) |
startup_timeout_sec | Option<Duration> | Timeout for server initialization (default: 10 seconds) |
tool_timeout_sec | Option<Duration> | Timeout for individual tool calls (default: 60 seconds) |
enabled_tools | Option<Vec<String>> | Allowlist of tool names (if set, only these tools are available) |
disabled_tools | Option<Vec<String>> | Denylist of tool names (these tools are blocked) |
scopes | Option<Vec<String>> | OAuth scopes for StreamableHttp servers |
Sources: codex-rs/core/src/config/types.rs62-101 codex-rs/core/src/mcp_connection_manager.rs74-75
MCP servers can communicate via two transport mechanisms: Stdio (subprocess) or StreamableHttp (HTTP connection).
Sources: codex-rs/core/src/config/types.rs232-262 codex-rs/cli/src/mcp_cmd.rs76-127
Stdio transport launches an MCP server as a subprocess and communicates via stdin/stdout.
Configuration Fields:
command: Path to the executableargs: Command-line argumentsenv: Static environment variables (key-value pairs set for the subprocess)env_vars: List of environment variable names to propagate from the parent processcwd: Working directory for the subprocess (optional)Example:
Sources: codex-rs/core/src/config/types.rs232-246 codex-rs/core/tests/suite/rmcp_client.rs84-116 codex-rs/cli/tests/mcp_add_remove.rs20-45
StreamableHttp transport connects to an MCP server via HTTP, supporting OAuth authentication.
Configuration Fields:
url: Server endpoint URLbearer_token_env_var: Name of environment variable containing the bearer tokenhttp_headers: Static HTTP headers (key-value pairs)env_http_headers: HTTP headers whose values come from environment variables (key: header name, value: env var name)Example:
Sources: codex-rs/core/src/config/types.rs247-261 codex-rs/cli/tests/mcp_add_remove.rs108-139
Tool filtering controls which tools from an MCP server are available to the model. Filtering is implemented via the ToolFilter structure.
Filter Rules:
enabled_tools is set (allowlist), only tools in this list are alloweddisabled_tools is set (denylist), tools in this list are blockedExample:
Sources: codex-rs/core/src/mcp_connection_manager.rs802-839 codex-rs/core/src/mcp_connection_manager.rs714-723
Requirements-based filtering allows organizations to enforce which MCP servers are permitted in Codex installations. This is implemented through configuration constraints (typically from requirements.toml or MDM on macOS) and is applied during configuration loading via the ConfigRequirements system.
Requirements specify an allowlist of MCP servers by their transport identity. Only servers matching a requirement entry are enabled; all others are automatically disabled.
Requirement Matching Rules:
command fieldurl fieldKey Functions:
filter_mcp_servers_by_requirements: Applies requirement constraints to server map codex-rs/core/src/config/mod.rs598-621mcp_server_matches_requirement: Checks if server matches requirement identity codex-rs/core/src/config/mod.rs673-691constrain_mcp_servers: Wraps filtering in Constrained<T> wrapper codex-rs/core/src/config/mod.rs623-636When a server is filtered out by requirements, its disabled_reason field is set to McpServerDisabledReason::Requirements { source }, where source indicates the origin of the requirement (e.g., requirements.toml or MDM).
Example Configuration:
If a user configures an unapproved server:
The server will be automatically disabled with disabled_reason = "Requirements (requirements.toml)".
Sources: codex-rs/core/src/config/mod.rs598-636 codex-rs/core/src/config/mod.rs673-691 codex-rs/core/src/config/types.rs44-59
Codex configures two types of timeouts for MCP servers:
| Timeout | Default | Config Field | Description |
|---|---|---|---|
| Startup | 10 seconds | startup_timeout_sec | Time allowed for server initialization and initial tool listing |
| Tool Call | 60 seconds | tool_timeout_sec | Time allowed for individual tool invocations |
Constants:
DEFAULT_STARTUP_TIMEOUT: 10 seconds codex-rs/core/src/mcp_connection_manager.rs86DEFAULT_TOOL_TIMEOUT: 60 seconds codex-rs/core/src/mcp_connection_manager.rs89Example:
Sources: codex-rs/core/src/mcp_connection_manager.rs86 codex-rs/core/src/mcp_connection_manager.rs89 codex-rs/core/src/config/types.rs78-88
MCP tool names are qualified with the server name to prevent collisions and sanitized to meet API requirements.
Transformation Rules:
mcp__<server_name>__ codex-rs/core/src/mcp_connection_manager.rs126-129^[a-zA-Z0-9_-]+$ (OpenAI API requirement) codex-rs/core/src/mcp_connection_manager.rs94-109Constants:
MCP_TOOL_NAME_DELIMITER: "__" codex-rs/core/src/mcp_connection_manager.rs82MAX_TOOL_NAME_LENGTH: 64 codex-rs/core/src/mcp_connection_manager.rs83Sources: codex-rs/core/src/mcp_connection_manager.rs99-163
MCP servers can be configured at multiple layers, following Codex's layered configuration system (see Configuration System).
| Layer | Path | Precedence |
|---|---|---|
| System | /etc/codex/config.toml | Lowest |
| User | ~/.codex/config.toml | Medium |
| Project | .codex/config.toml | High |
| CLI | --config overrides | Highest |
Configuration Loading:
The load_global_mcp_servers function loads MCP server configurations from the user's home directory:
Sources: codex-rs/core/src/config/mod.rs693-726 codex-rs/cli/src/mcp_cmd.rs199-202
The codex-apps MCP server receives special treatment with tool list caching:
CODEX_APPS_TOOLS_CACHE static codex-rs/core/src/mcp_connection_manager.rs180-181Caching Logic:
Sources: codex-rs/core/src/mcp_connection_manager.rs91 codex-rs/core/src/mcp_connection_manager.rs519-546 codex-rs/core/src/mcp_connection_manager.rs1023-1069
Servers marked with required = true will cause Codex to fail startup if they cannot be initialized:
The required_startup_failures method checks for failed required servers and returns failures codex-rs/core/src/mcp_connection_manager.rs491-514
Sources: codex-rs/core/src/mcp_connection_manager.rs491-514
Stdio transport supports two types of environment variable configuration:
env: Static key-value pairs set directly in configenv_vars: List of variable names to propagate from parent processExample:
When the MCP server subprocess is spawned:
env are set to their configured valuesenv_vars are read from the current process environment and propagatedSources: codex-rs/core/tests/suite/rmcp_client.rs84-116 codex-rs/cli/tests/mcp_list.rs52-64
For StreamableHttp transport, bearer tokens can be provided via environment variables:
The bearer token resolution happens during MCP client initialization codex-rs/core/src/mcp_connection_manager.rs896-922
Error Handling:
Sources: codex-rs/core/src/mcp_connection_manager.rs896-922
Here is a comprehensive example showing multiple MCP servers with different configurations:
Sources: codex-rs/core/tests/suite/rmcp_client.rs84-116 codex-rs/cli/tests/mcp_add_remove.rs16-69
Server names must conform to specific rules enforced by the validate_server_name function:
Validation Rules:
a-z, A-Z, 0-9, -, _Implementation:
Sources: codex-rs/cli/src/mcp_cmd.rs819-830 codex-rs/core/src/mcp_connection_manager.rs1144-1165
MCP server configurations are persisted using the ConfigEditsBuilder API:
Sources: codex-rs/cli/src/mcp_cmd.rs257-261 codex-rs/core/src/config/edit.rs43
Sources: codex-rs/cli/src/mcp_cmd.rs306-310 codex-rs/cli/tests/mcp_add_remove.rs48-54
Refresh this wiki