How to add MCP servers to OpenAI Codex

1. Find the config file

• ~/.codex/config.toml (user)
• .codex/config.toml (project, trusted projects only)

One [mcp_servers.<name>] table per server. The CLI, IDE extension and ChatGPT desktop app share this config.

2. Add a local (stdio) server

Example: Context7, which runs locally with npx.

codex mcp add context7 -- npx -y @upstash/context7-mcp

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

3. Add a remote (HTTP) server

Example: Notion's hosted server. You sign in with OAuth the first time it connects.

codex mcp add notion --url https://mcp.notion.com/mcp

[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"

4. If it won't connect

• Validate the file. One trailing comma breaks the whole file.
• Check the top-level key: VS Code uses servers; Claude Code, Cursor and Antigravity use mcpServers; Codex uses TOML tables.
• If npx isn't found, the app may not see your shell's PATH (common with nvm). Use the full path to npx.
• Restart the agent or reload the window after editing.