How to add an MCP server to Codex

Quick answer

1. Run codex mcp add <name> -- <command> <args>. For example codex mcp add context7 -- npx -y @upstash/context7-mcp (the example OpenAI's docs use).
2. Run codex mcp list to confirm it is saved.
3. Start codex and type /mcp to see the active servers.

The command writes a [mcp_servers.<name>] table into ~/.codex/config.toml. You can edit that file directly for anything the command does not cover. The IDE extension and desktop app also have an MCP servers screen (in settings) that edits the same configuration.

Where the config lives

• Global: ~/.codex/config.toml (on Windows, in .codex under your user folder).
• Project: .codex/config.toml in a project, which Codex reads for trusted projects only.

The ChatGPT desktop app, the Codex CLI and the IDE extension share this configuration, so you set a server up once. ChatGPT on the web does not read your local Codex files; it uses plugins instead.

Option 1: codex mcp add

codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>

Everything after -- is the command that starts the server. Put --env options before it. A few real examples, using servers listed on PluginStack:

# Context7: current library docs (example from the OpenAI docs)
codex mcp add context7 -- npx -y @upstash/context7-mcp

# Official Memory server
codex mcp add memory -- npx -y @modelcontextprotocol/server-memory

# Official Filesystem server: the last argument is the folder it may access
codex mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/you/projects

See Context7, Memory and Filesystem. The official TypeScript servers need Node 24 or newer from v2 onward (what changed).

Other commands

• codex mcp list shows the configured servers.
• codex mcp --help lists all MCP commands.
• codex mcp login <server-name> starts the OAuth login for a server that supports it.

A remote (HTTP) server

For a hosted server, pass its address with --url instead of a command:

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

Option 2: edit config.toml

Each server is a [mcp_servers.<name>] table. For a local (stdio) server, command is required; args, env, env_vars and cwd are optional:

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

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 20   # default is 10

The table name (filesystem) is the label you choose. Save the file and restart Codex (in the IDE extension, use Restart extension).

Environment variables and API keys

• env sets values for the server: env = { API_KEY = "value" }.
• env_vars lists variable names to allow and forward from your own environment, such as env_vars = ["API_KEY"], so the secret does not have to sit in the file.

Prefer env_vars for real keys, and never commit a config.toml that contains one. A project-level .codex/config.toml is easy to commit by accident.

A remote server in config.toml

[mcp_servers.example]
url = "https://mcp.example.com"
bearer_token_env_var = "EXAMPLE_TOKEN"   # token read from this variable, sent in Authorization

For HTTP servers, url is required. You can add a bearer token from an environment variable (bearer_token_env_var), static headers (http_headers), or headers read from variables (env_http_headers). With none of those, Codex tries stored OAuth credentials, so run codex mcp login <name> for servers that use OAuth.

Useful options

• startup_timeout_sec: seconds to wait for the server to start. Default 10. Raise it if the first npx download is slow.
• tool_timeout_sec: seconds a tool call may run. Default 60.
• enabled = false: switch a server off without deleting its config.
• required = true: make Codex fail at startup if that server cannot initialise.
• enabled_tools and disabled_tools: allow or deny specific tool names.
• default_tools_approval_mode: how Codex asks before running the server's tools (auto, prompt, writes or approve).

OpenAI's configuration reference has the complete list of MCP options. Settings change between Codex releases, so check it for your version.

Check that it works

1. Run codex mcp list: the server should appear.
2. Start codex and type /mcp: the server should be listed as active.
3. Ask for something only that server can do, for example "Use the memory server to remember that I prefer tabs", and approve the tool call if asked.

Common errors and fixes

• The server does not appear: check the table is [mcp_servers.<name>] (plural mcp_servers) and that the TOML is valid. For a project file, the project must be trusted.
• It times out on the first run: the first npx -y run downloads the package. Raise startup_timeout_sec, or run the command once by hand so it is cached.
• `spawn npx ENOENT`, or it fails only on Windows: update Codex, then see Fix "spawn npx ENOENT" on Windows.
• The server exits at once: run its command yourself in a terminal to see why. Fix MCP error -32000 walks through it.
• An OAuth server stays unauthenticated: run codex mcp login <name>; in the desktop app or IDE extension, use Authenticate in the MCP servers list.

Using Codex alongside other tools? The same servers can be added to Cursor and Claude Code. More about the agent itself: Codex CLI.

FAQ

Is the config the same for the CLI and the IDE extension?

Yes. OpenAI's docs say the desktop app, CLI and IDE extension share MCP configuration, so you can switch between them without redoing setup.

Where do I put an API key?

Use env_vars to forward a variable from your shell, or bearer_token_env_var for remote servers, so the key stays out of the file. If you use env or codex mcp add --env, the value is saved in config.toml; keep that file private.

How do I turn a server off without removing it?

Set enabled = false in its [mcp_servers.<name>] table.