valknar/llmx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[MCP] Improve docs (#4811)

Browse Source 
Updated, expanded on, clarified, and deduplicated some MCP docs
This commit is contained in:
Gabriel Peal
2025-10-06 08:43:50 -07:00
committed by GitHub
parent 36f1cca1b1
commit 721003c552
5 changed files with 48 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/advanced.md
View File

@@ -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

44
docs/config.md
View File

@@ -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 <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`: