Model Context Protocol

Model Context Protocol (MCP) is a protocol for connecting models to additional tools and context. It’s a great option for you to provide Codex access to documentation for different libraries or have it interact with some of your other developer tools like your browser or Figma.

MCP servers are supported by both the Codex CLI and the Codex IDE extension.

Supported MCP features

• STDIO servers (servers that can be launched via a command on your computer)
  • Environment variables
• Streamable HTTP servers (servers that can be accessed via a URL)
  • Bearer token authentication
  • OAuth authentication (requires experimental_use_rmcp_client = true in config.toml)

Connect Codex to a MCP server

MCP configuration for Codex is stored within the ~/.codex/config.toml configuration file alongside other Codex configuration options.

Configuration is shared between the CLI and the IDE extension. So once you have configured your MCP servers, you can seamlessly switch between the two Codex clients.

To configure your MCP servers, you have two options:

1. Using the CLI: If you have the Codex CLI installed, you can use the codex mcp command to configure your MCP servers.
2. Modifing the config file directly: Alternatively, you can modify the config.toml file directly.

Configuration - CLI

Add a MCP server

codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>

For example, to add Context7 (a free MCP server for developer documentation), you can run the following command:

codex mcp add context7 -- npx -y @upstash/context7-mcp

Other CLI commands

To see all available MCP commands, you can run codex mcp --help.

Terminal UI (TUI)

Once you have launched codex and are running the TUI, you can use /mcp to see your actively connected MCP servers.

Configuration - config.toml

For more fine grained control over MCP server options, you can manually edit the ~/.codex/config.toml configuration file. If you are using the IDE extension, you can find the config file by clicking the gear icon in the top right corner of the extension and then clicking MCP settings > Open config.toml.

Each MCP server is configured with a [mcp.<server-name>] table in the config file.

STDIO servers

• command - [Required] The command to launch the server
• args - [Optional] The arguments to pass to the server
• env - [Optional] The environment variables to set for the server

Streamable HTTP servers

• url - [Required] The URL to access the server
• bearer_token - [Optional] The bearer token to use in an Authorization header

Other configuration options

• startup_timeout_sec - [Optional] The timeout in seconds for the server to start
• tool_timeout_sec - [Optional] The timeout in seconds for the server to execute a tool
• experimental_use_rmcp_client - [Optional] Whether to use the RMCP client to connect to the server
  • Enables a new implementation for STDIO servers and enables OAuth authentication for streamable HTTP servers
  • Top-level property, not inside the table for a specific server

config.toml Examples

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"

experimental_use_rmcp_client = true

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"

Examples of useful MCPs

There is an ever growing list of useful MCP servers that can be helpful while you are working with Codex.

Some of the most common MCPs we’ve seen are:

• Context7 — connect to a wide range of up-to-date developer documentation
• Figma Local and Remote - access to your Figma designs
• Playwright - control and inspect a browser using Playwright
• Chrome Developer Tools — control and inspect a Chrome browser
• Sentry — access to your Sentry logs
• GitHub — Control over your GitHub account beyond what git allows (like controlling PRs, issues, etc.)

Running Codex as an MCP server

Additionally, to connecting Codex to MCP servers, you can also run Codex as an MCP server. This way you can connect it to other MCP clients such as an agent you are building using the OpenAI Agents SDK.

To start Codex as an MCP server, you can use the following command:

codex mcp-server

You can launch a Codex MCP server with the Model Context Protocol Inspector:

npx @modelcontextprotocol/inspector codex mcp-server

Send a tools/list request and you will see that there are two tools available:

codex - Run a Codex session. Accepts configuration parameters matching the Codex Config struct. The codex tool takes the following properties:

codex-reply - Continue a Codex session by providing the conversation id and prompt. The codex-reply tool takes the following properties:

Trying it Out

Use the MCP inspector and codex mcp-server to build a simple tic-tac-toe game with the following settings:

Click “Run Tool” and you should see a list of events emitted from the Codex MCP server as it builds the game.