[MCP] Improve docs (#4811)

Updated, expanded on, clarified, and deduplicated some MCP docs

Author: gpeal

README.md

@@ -61,7 +61,7 @@ You can also use Codex with an API key, but this requires [additional setup](./d
 
 ### Model Context Protocol (MCP)
 
-Codex CLI supports [MCP servers](./docs/advanced.md#model-context-protocol-mcp). Enable by adding an `mcp_servers` section to your `~/.codex/config.toml`.
+Codex can access MCP servers. To configure them, refer to the [config docs](./docs/config.md#mcp_servers).
 
 ### Configuration
 

codex-rs/README.md

@@ -23,9 +23,15 @@ Codex supports a rich set of configuration options. Note that the Rust CLI uses
 
 ### Model Context Protocol Support
 
-Codex CLI functions as an MCP client that can connect to MCP servers on startup. See the [`mcp_servers`](../docs/config.md#mcp_servers) section in the configuration documentation for details.
+#### MCP client
 
-It is still experimental, but you can also launch Codex as an MCP _server_ by running `codex mcp-server`. Use the [`@modelcontextprotocol/inspector`](https://github.com/modelcontextprotocol/inspector) to try it out:
+Codex CLI functions as an MCP client that allows the Codex CLI and IDE extension to connect to MCP servers on startup. See the [`configuration documentation`](../docs/config.md#mcp_servers) for details.
+
+#### MCP server (experimental)
+
+Codex can be launched as an MCP _server_ by running `codex mcp-server`. This allows _other_ MCP clients to use Codex as a tool for another agent.
+
+Use the [`@modelcontextprotocol/inspector`](https://github.com/modelcontextprotocol/inspector) to try it out:
 
 ```shell
 npx @modelcontextprotocol/inspector codex mcp-server

codex-rs/docs/codex_mcp_interface.md

@@ -1,6 +1,6 @@
-# Codex MCP Interface [experimental]
+# Codex MCP Server Interface [experimental]
 
-This document describes Codex’s experimental MCP interface: a JSON‑RPC API that runs over the Model Context Protocol (MCP) transport to control a local Codex engine.
+This document describes Codex’s experimental MCP server interface: a JSON‑RPC API that runs over the Model Context Protocol (MCP) transport to control a local Codex engine.
 
 - Status: experimental and subject to change without notice
 - Server binary: `codex mcp-server` (or `codex-mcp-server`)

docs/advanced.md

@@ -16,15 +16,7 @@ See the Rust documentation on [`RUST_LOG`](https://docs.rs/env_logger/latest/env
 
 ## Model Context Protocol (MCP)
 
-The Codex CLI can be configured to leverage MCP servers by defining an [`mcp_servers`](./config.md#mcp_servers) section in `~/.codex/config.toml`. It is intended to mirror how tools such as Claude and Cursor define `mcpServers` in their respective JSON config files, though the Codex format is slightly different since it uses TOML rather than JSON, e.g.:
-
-```toml
-# IMPORTANT: the top-level key is `mcp_servers` rather than `mcpServers`.
-[mcp_servers.server-name]
-command = "npx"
-args = ["-y", "mcp-server"]
-env = { "API_KEY" = "value" }
-```
+The Codex CLI and IDE extension is a MCP client which means that it can be configured to connect to MCP servers. For more information, refer to the [`config docs`](./config.md#connecting-to-mcp-servers).
 
 ## Using Codex as an MCP Server
 

docs/config.md

@@ -335,40 +335,47 @@ Codex provides three main Approval Presets:
 
 You can further customize how Codex runs at the command line using the `--ask-for-approval` and `--sandbox` options.
 
-## MCP Servers
+## Connecting to MCP servers
 
-You can configure Codex to use [MCP servers](https://modelcontextprotocol.io/about) to give Codex access to external applications, resources, or services such as [Playwright](https://github.com/microsoft/playwright-mcp), [Figma](https://www.figma.com/blog/design-context-everywhere-you-build/), [documentation](https://context7.com/), and [more](https://github.com/mcp?utm_source=blog-source&utm_campaign=mcp-registry-server-launch-2025).
+You can configure Codex to use [MCP servers](https://modelcontextprotocol.io/about) to give Codex access to external applications, resources, or services.
 
-### Server transport configuration
+### Server configuration
 
 #### STDIO
 
+[STDIO servers](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio) are MCP servers that you can launch directly via commands on your computer.
+
 ```toml
 # The top-level table name must be `mcp_servers`
 # The sub-table name (`server-name` in this example) can be anything you would like.
-[mcp_servers.server-name]
+[mcp_servers.server_name]
 command = "npx"
 # Optional
 args = ["-y", "mcp-server"]
 # Optional: propagate additional env vars to the MVP server.
 # A default whitelist of env vars will be propagated to the MCP server.
 # https://github.com/openai/codex/blob/main/codex-rs/rmcp-client/src/utils.rs#L82
 env = { "API_KEY" = "value" }
+# or
+[mcp_servers.server_name.env]
+API_KEY = "value"
 ```
 
 #### Streamable HTTP
 
+[Streamable HTTP servers](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) enable Codex to talk to resources that are accessed via a http url (either on localhost or another domain).
+
 ```toml
 # Streamable HTTP requires the experimental rmcp client
 experimental_use_rmcp_client = true
 [mcp_servers.figma]
-url = "http://127.0.0.1:3845/mcp"
+url = "https://mcp.linear.app/mcp"
 # Optional bearer token to be passed into an `Authorization: Bearer <token>` header
-# Use this with caution because the token is in plaintext.
+# Use this with caution because the token is in plaintext and can be read by Codex itself.
 bearer_token = "<token>"
 ```
 
-Refer to the MCP CLI commands for oauth login
+For oauth login, you must enable `experimental_use_rmcp_client = true` and then run `codex mcp login server_name`
 
 ### Other configuration options
 
@@ -381,17 +388,25 @@ tool_timeout_sec = 30
 
 ### Experimental RMCP client
 
-Codex is transitioning to the [official Rust MCP SDK](https://github.com/modelcontextprotocol/rust-sdk) and new functionality such as streamable http servers will only work with the new client.
+Codex is transitioning to the [official Rust MCP SDK](https://github.com/modelcontextprotocol/rust-sdk).
+
+The flag enabled OAuth support for streamable HTTP servers and uses a new STDIO client implementation.
 
 Please try and report issues with the new client. To enable it, add this to the top level of your `config.toml`
 
 ```toml
 experimental_use_rmcp_client = true
+
+[mcp_servers.server_name]
+…
 ```
 
 ### MCP CLI commands
 
 ```shell
+# List all available commands
+codex mcp --help
+
 # Add a server (env can be repeated; `--` separates the launcher command)
 codex mcp add docs -- docs-server --port 4000
 
@@ -413,6 +428,19 @@ codex mcp login SERVER_NAME
 codex mcp logout SERVER_NAME
 ```
 
+## 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](https://github.com/upstash/context7) — connect to a wide range of up-to-date developer documentation
+- Figma [Local](https://developers.figma.com/docs/figma-mcp-server/local-server-installation/) and [Remote](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) - access to your Figma designs
+- [Playwright](https://www.npmjs.com/package/@playwright/mcp) - control and inspect a browser using Playwright
+- [Chrome Developer Tools](https://github.com/ChromeDevTools/chrome-devtools-mcp/) — control and inspect a Chrome browser
+- [Sentry](https://docs.sentry.io/product/sentry-mcp/#codex) — access to your Sentry logs
+- [GitHub](https://github.com/github/github-mcp-server) — Control over your GitHub account beyond what git allows (like controlling PRs, issues, etc.)
+
 ## shell_environment_policy
 
 Codex spawns subprocesses (e.g. when executing a `local_shell` tool-call suggested by the assistant). By default it now passes **your full environment** to those subprocesses. You can tune this behavior via the **`shell_environment_policy`** block in `config.toml`: