Where the config lives
- All platforms:
~/.codex/config.toml
Servers go under the mcp_servers key as TOML tables.
What Codex CLI can run
- Local servers (stdio)
- Remote servers (HTTP)
- Remote servers (SSE)
223 of the 508 servers in the catalog run natively in Codex CLI; the rest work through the mcp-remote bridge, which the generated configs include automatically.
Step by step
- Open `~/.codex/config.toml`.
- Add a `[mcp_servers.<name>]` table with `command`, `args` and an optional `env = { KEY = "value" }`.
- Start `codex`; the servers load on startup.
Reloading: Restart `codex` after editing config.toml.
Example: the Filesystem server in Codex CLI
The official reference server for file access. Replace the directory with the folder you want the assistant to see.
Add to ~/.codex/config.toml
toml
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]Troubleshooting
- Codex fails to parse config.toml
- TOML strings need double quotes, and `args` is an array: `args = ["-y", "pkg"]`.
- `SyntaxError` or `Unsupported engine` when the server starts
- Most MCP servers need Node.js 18 or newer (`node -v`). If you use nvm, the client may not see your shell's Node: point `command` at the absolute path of `npx`.
- `uvx: command not found` for Python servers
- Install uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`, or `winget install astral-sh.uv` on Windows), then restart the client so it picks up the new PATH.
- The server starts but every tool call fails with 401 or 403
- Its API key is missing or wrong. Put it in the server's `env` block (or the header for remote servers) — never in a file you commit.
Official documentation: Codex CLI MCP docs
Setting up several servers at once?
Tick them in the catalog and the setup builder merges them into one Codex CLI config.
Open the setup builder for Codex CLI