How to Add an MCP Server to Codex CLI

You add an MCP server to Codex CLI with the codex mcp add command.

Model Context Protocol (MCP) lets ChatGPT and Codex use tools and information from other systems by running servers that describe available tools and handle requests. As of 9 November 2026, OpenAI documents the codex mcp add command and config.toml tables for local and remote servers.

The ChatGPT desktop application, Codex Command Line Interface (CLI), and Integrated Development Environment (IDE) extension share MCP configuration for the same Codex host. When you configure your servers once, you can switch among those clients without repeating the setup steps.

How to Add an MCP Server to Codex CLI

Running codex mcp add adds an MCP server from the command line. You pass the server name, optional environment variables, and the server command after a double dash.

For example, OpenAI provides a command to connect Context7, which OpenAI describes as a free MCP server for developer documentation: codex mcp add context7 -- npx -y @upstash/context7-mcp.

The general syntax follows the pattern codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>.

Codex supports Standard Input and Output (STDIO) servers and Streamable Hypertext Transfer Protocol (HTTP) servers. A STDIO server runs as a local process started by a command, while a Streamable HTTP server is one you access at an address.

After you add a server, check it three ways:

• Run codex mcp list to print every configured server and confirm the registration succeeded.
• Open the Codex Text User Interface (TUI) and run /mcp to inspect which servers are currently active.
• Run codex mcp --help in your terminal to review all available MCP subcommands and arguments.

Configure MCP in config.toml

Codex stores its MCP definitions in a config.toml file alongside other user settings. The default configuration lives at ~/.codex/config.toml, but you can also scope definitions to a specific workspace by creating .codex/config.toml inside trusted projects.

Each server configuration requires its own [mcp_servers.<server-name>] table header. For complete documentation on valid structure and top-level options, OpenAI maintains a searchable configuration reference detailing every supported key.

To define Context7 manually in config.toml, add [mcp_servers.context7] with command = "npx", set args = ["-y", "@upstash/context7-mcp"], list allowed variables with env_vars = ["LOCAL_TOKEN"], and create a [mcp_servers.context7.env] subtable containing MY_ENV_VAR = "MY_ENV_VALUE".

If you have not installed Codex CLI yet, see Codex CLI on Linux or Codex CLI on Windows.

A STDIO server uses these keys:

• command: the required command string or executable path that launches the local server process.
• args: an optional array of command-line argument strings passed to the executable on startup.
• env: optional environment variables to set for the server.
• env_vars: optional environment variables to allow and forward.
• cwd: an optional working directory path from which Codex launches the server process.

Remote MCP Servers in config.toml

Streamable HTTP servers connect Codex CLI to remote services across a network endpoint specified by a URL.

OpenAI provides a configuration example for Figma using a remote table: [mcp_servers.figma] with url = "https://mcp.figma.com/mcp", bearer_token_env_var = "FIGMA_OAUTH_TOKEN", and http_headers = { "X-Figma-Region" = "us-east-1" }.

The bearer_token_env_var setting names the environment variable that holds the bearer token Codex sends in the Authorization header.

A Streamable HTTP server uses these keys:

• url: the required server address.
• auth: optional. oauth is the default and uses stored MCP OAuth credentials. chatgpt uses the current ChatGPT session for the trusted first-party ChatGPT origin, with stored OAuth as a fallback.
• bearer_token_env_var: the optional name of the host environment variable storing a bearer token.
• http_headers: an optional map assigning static string values to custom HTTP request header names.

MCP Settings and Defaults

On our reading of OpenAI's MCP page as of 9 November 2026, two settings control waiting at startup. startup_timeout_sec is the timeout for one server to start. mcp_optional_startup_grace_ms is a top-level setting for how long Codex waits for optional servers when building the initial tool catalog.

OpenAI documents a Chrome Developer Tools example combining these parameters: [mcp_servers.chrome_devtools] with url = "http://localhost:3000/mcp", enabled_tools = ["open", "screenshot"], disabled_tools = ["screenshot"], default_tools_approval_mode = "prompt", startup_timeout_sec = 20, tool_timeout_sec = 45, and enabled = true.

OAuth Servers and Login for Codex CLI MCP

When a remote server requires Open Authorization (OAuth), run codex mcp login <server-name> to sign in.

If an endpoint requires a pre-registered OAuth client, register it using codex mcp add example --url https://mcp.example.com --oauth-client-id my-client. For confidential clients, pass --oauth-client-secret reading from a shell variable like "$MCP_CLIENT_SECRET". Codex saves this value into mcp_servers.example.oauth.client_secret inside config.toml, and OpenAI states that you must keep that file private and out of version control.

You can define requested OAuth permissions by setting mcp_servers.<server-name>.scopes in config.toml, or supply them for a single session using codex mcp login <server-name> --scopes read,write. Codex selects client registration methods automatically by default, but you can pass --oauth-client-registration cimd for Client ID Metadata Documents or --oauth-client-registration dcr for Dynamic Client Registration.

In a terminal without a local browser, follow these steps:

• Run codex mcp login <server-name> --no-browser, which prints an authorization URL.
• Open the printed authorization URL in a browser and sign in.
• Paste the full redirect URL back into the terminal, even if the browser cannot load the callback page.

When a Codex CLI MCP Server Is Slow or Fails to Start

OpenAI's MCP page lists configuration parameters for server readiness and gives no troubleshooting steps for a slow or unresponsive local server.

Our own reasoning, which OpenAI does not state: diagnose a new server before you tune it. Add it with codex mcp add, run codex mcp list and open /mcp. Set required = true or change timeouts afterward, because those settings change when startup counts as a failure.

OpenAI's Context7 example starts the server with npx -y, and the default startup_timeout_sec is 10 seconds.

For additional command syntax, review the OpenAI Model Context Protocol documentation or execute codex mcp --help.

The documented levers are:

• startup_timeout_sec: the timeout in seconds for a server to start, 10 by default. A higher value gives a slow-starting server more time.
• tool_timeout_sec: the timeout in seconds for a server to run a tool, 60 by default. A higher value gives a long-running tool more time.
• required and startup_readiness: required = true makes startup fail if an enabled server is not ready, so leave it off for a server that may be slow. startup_readiness = "catalog" lets a valid cached tool catalog satisfy startup while the server connects, and tool calls still need a live connection.
• enabled: set false to disable a server without deleting it.
• mcp_optional_startup_grace_ms: adjust this top-level parameter from its 1000 millisecond default, or set it to 0 to make Codex wait the full startup_timeout_sec for optional servers.
• enabled_tools and disabled_tools: an allow list and a deny list applied after it.

Our Takeaway for Codex CLI MCP Setup

On our reading of OpenAI's documentation as of 9 November 2026, add a server with codex mcp add for a quick start. Move durable setups into config.toml, user-wide or project-scoped for trusted projects.

When a local process or remote endpoint is slow to start, the documented lever is startup_timeout_sec (default 10 seconds).

It does not suit readers who want a managed enterprise rollout, or readers whose server fails for reasons OpenAI's page does not cover. Those readers should run codex mcp --help and read OpenAI's Model Context Protocol documentation, then check the server's own documentation.

Changes by OpenAI to default timeout values, CLI command flags, or configuration keys would alter these instructions.

To begin your Codex CLI MCP configuration, run codex mcp add context7 -- npx -y @upstash/context7-mcp in your terminal and verify the connection with codex mcp list.