Add MCP servers to Codex CLI

MCP servers give Codex CLI access to external tools and data over the Model Context Protocol 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.

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>]:

[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:

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:

[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:

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.

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.