diff --git a/README.md b/README.md index f17f605e..c9cc4e1f 100644 --- a/README.md +++ b/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 diff --git a/codex-rs/README.md b/codex-rs/README.md index f5a5b838..a05a8d48 100644 --- a/codex-rs/README.md +++ b/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 diff --git a/codex-rs/docs/codex_mcp_interface.md b/codex-rs/docs/codex_mcp_interface.md index 1291d3ee..eb0442fe 100644 --- a/codex-rs/docs/codex_mcp_interface.md +++ b/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`) diff --git a/docs/advanced.md b/docs/advanced.md index d5012c28..7c986f58 100644 --- a/docs/advanced.md +++ b/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 diff --git a/docs/config.md b/docs/config.md index f079adda..aa45acc8 100644 --- a/docs/config.md +++ b/docs/config.md @@ -335,18 +335,20 @@ 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"] @@ -354,21 +356,26 @@ args = ["-y", "mcp-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 ` 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 = "" ``` -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`: