# Add MCP servers to Codex CLI

> Enable MCP servers in OpenAI Codex CLI: config.toml location, the exact mcp_servers TOML shape, a worked example, and how to confirm it loaded.

- Canonical: https://guides-ai.com/guides/codex-cli-mcp/
- Plate 14.08 · Topic: Other coding agents (https://guides-ai.com/topics/agents/)
- Published: 21 Oct 2026 · 3 min read
- Source site: guides-ai — https://guides-ai.com/

MCP servers give [Codex CLI](/guides/codex-cli-first-steps/) access to external tools and data over the [Model Context Protocol](/glossary/#mcp) that Claude Code uses too. Codex stores them in TOML, and the CLI, the IDE extension and the ChatGPT desktop app all share that config. Everything below is from the [official Codex MCP docs](https://developers.openai.com/codex/mcp).

## 1. Find the config file

Codex reads `~/.codex/config.toml` for user-wide servers. A project can add `.codex/config.toml`, but it applies only to trusted projects. Create the file if it does not exist.

## 2. Add a filesystem server

Add one table per server, named `[mcp_servers.<name>]`:

```toml
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
```

Here `command` is required, and `args`, `env`, `env_vars`, `cwd`, `enabled` and `required` are optional. Timeouts default to `startup_timeout_sec = 10` and `tool_timeout_sec = 60`.

## 3. Or let the CLI write it

This adds the same STDIO server without editing TOML by hand:

```bash
codex mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/projects
```

Pass `--env KEY=VALUE` before the `--` to forward an environment variable.

## 4. Add a remote HTTP server

Streamable HTTP servers use a `url` instead of a command:

```toml
[mcp_servers.example]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "EXAMPLE_TOKEN"
```

For OAuth servers, run `codex mcp login example` once to authenticate.

## 5. Launch and confirm it loaded

List servers from your shell, or type `/mcp` inside the Codex TUI:

```bash
codex mcp list
```

A healthy server appears with its tools, and Codex can call them during a task. The Claude Code analog is [install an MCP server in Claude Code](/guides/install-mcp-server-claude-code/).

## Verify it worked

- **Server missing from `codex mcp list`** Check the table name is exactly `[mcp_servers.name]`, then restart Codex.
- **`spawn npx ENOENT`** Node is not on PATH; install Node or give `command` an absolute path.
- **Remote server returns 401** The token is missing; set the variable named in `bearer_token_env_var`, or run `codex mcp login`.

Source: [Codex MCP docs](https://developers.openai.com/codex/mcp).