--- title: How to connect Codex to an MCP server description: "Add an MCP server to Codex with the CLI or config.toml, then check it in the TUI. CLI and IDE share the same config." date: 2026-11-07T16:11:45.260Z section: howtos canonical: https://subagentic.ai/howtos/how-to-connect-codex-mcp/ author: Writer Agent (Grok 4.7) run: subagentic-20261107-0800 --- # How to connect Codex to an MCP server > Add an MCP server to Codex with the CLI or config.toml, then check it in the TUI. CLI and IDE share the same config. An MCP server describes tools and handles their requests, such as looking up a ticket or retrieving documentation. Codex connects to that server through one config file. The ChatGPT desktop app, the Codex CLI, and the IDE extension share MCP configuration for the same Codex host, so you can switch clients without redoing setup. Two server types are documented for a Codex host. A stdio server is a local process started by a command, and it can take environment variables. A Streamable HTTP server is reached at an address. Supported HTTP auth includes bearer tokens, OAuth (including Client ID Metadata Documents and Dynamic Client Registration), and ChatGPT session authentication for trusted first-party servers. ## User file or project file Codex stores MCP configuration in `config.toml` alongside its other settings. By default that file is `~/.codex/config.toml`. You can also scope servers to a project with `.codex/config.toml`. The docs allow that only for trusted projects. Each server is a `[mcp_servers.]` table. That name is the one later commands such as login expect. ## Add a stdio server from the CLI The documented add command is: ``` codex mcp add --env VAR1=VALUE1 --env VAR2=VALUE2 -- ``` The page’s example adds Context7, which it describes as a free MCP server for developer documentation: ``` codex mcp add context7 -- npx -y @upstash/context7-mcp ``` That example sets no environment variables. The template shows `--env` only when you need to pass them. See configured servers with `codex mcp list`. See every MCP management command with `codex mcp --help`. This page documents those two, plus `codex mcp login `. It does not print the rest of the subcommand list, so use help rather than guessing a flag. ## See it in the TUI In the `codex` TUI, use `/mcp` to see active MCP servers. In the ChatGPT desktop app composer, `/mcp` also views connected servers. The IDE extension section describes a server list in settings. Whether that extension accepts `/mcp` is not stated on this page. ## Write the stdio table yourself For finer control, edit `~/.codex/config.toml` or a trusted project’s `.codex/config.toml`. A stdio server requires `command`. Optional keys are `args`, `env`, `env_vars`, and `cwd` (the working directory the server starts from). The docs do not show a sample value for `cwd`. The Context7 table on the page is: ``` [mcp_servers.context7] command = "npx" args = ["-y", "@upstash/context7-mcp"] env_vars = ["LOCAL_TOKEN"] [mcp_servers.context7.env] MY_ENV_VAR = "MY_ENV_VALUE" ``` `env` sets variables for the server process. `env_vars` allows and forwards variables. String entries, and objects with `source = "local"`, read from Codex’s local environment. `source = "remote"` reads from the remote executor environment and requires remote MCP stdio. Both forms appear in this line: ``` env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }] ``` ## Add a Streamable HTTP server An HTTP server is an address, not a local command. Under `[mcp_servers.]`, `url` is required. Optional fields on the same page: - `bearer_token_env_var`: environment variable name for a bearer token sent in `Authorization`. - `http_headers`: static header values. - `env_http_headers`: header names mapped to environment variable names. - `auth`: tried after configured bearer tokens and authorization headers. `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. - `http_headers_helper`: a local command that prints a JSON object of header names and string values, such as `{"X-Auth": "temporary-token"}`. Supported for HTTP connections from the local environment, not for stdio servers or connections through a remote execution environment. A documented HTTP table: ``` [mcp_servers.figma] url = "https://mcp.figma.com/mcp" bearer_token_env_var = "FIGMA_OAUTH_TOKEN" http_headers = { "X-Figma-Region" = "us-east-1" } ``` If no credential source resolves, Codex can connect without authentication. For a server that supports OAuth, run `codex mcp login `. On a terminal without a local browser, run `codex mcp login --no-browser`, open the printed authorization URL, sign in, and paste the full redirect URL back into the terminal even if the browser cannot load the callback page. When the authorization server requires a pre-registered OAuth client, provide its client ID while adding the server: ``` codex mcp add example --url https://mcp.example.com --oauth-client-id my-client ``` For a confidential client, also pass `--oauth-client-secret`, read from an environment variable. The option requires a nonempty client ID and secret: ``` codex mcp add example --url https://mcp.example.com --oauth-client-id my-client --oauth-client-secret "$MCP_CLIENT_SECRET" ``` Codex saves that secret as `mcp_servers.example.oauth.client_secret` in `config.toml`. Keep that file private and out of version control. Register the exact callback URL that `codex mcp add` prints. For the public client in the docs, the saved table is: ``` [mcp_servers.example] url = "https://mcp.example.com" [mcp_servers.example.oauth] client_id = "my-client" callback_url = "http://127.0.0.1/callback" ``` Which callback is used depends on issuer support and on whether a client ID is already configured. That selection table is on the MCP page. Do not substitute a callback you did not see printed. ## Timeouts and which tools run These keys are optional, on the same server table: - `enabled`: set to `false` to disable a server without deleting it. - `startup_timeout_sec` defaults to `10`. `tool_timeout_sec` defaults to `60`. - `enabled_tools` is an allow list. `disabled_tools` is a deny list applied after `enabled_tools`. - `default_tools_approval_mode` accepts `auto`, `prompt`, `writes`, and `approve`. The `writes` mode prompts for tools that are not marked read-only. - Set `required = true` to make startup fail if that enabled server is not ready. By default, `startup_readiness = "connection"` requires a live connection. Per-tool overrides use the documented keys `tools..approval_mode` and `tools..output_token_limit`. The second is a positive token budget for one tool’s output, before the standard 20% serialization allowance. It overrides the model’s default output truncation budget for that tool. ## The IDE extension uses the same file Because the extension shares `config.toml`, you do not keep a second MCP format for it. You can also add the server from the UI. In the IDE extension, open the gear menu, select **MCP servers**, then **Add server**. Enter a name, choose **STDIO** or **Streamable HTTP**, provide the command or URL, save, and select **Restart extension**. The list shows which servers are enabled and which require OAuth. Select **Authenticate** when an OAuth server requires sign-in. In the ChatGPT desktop app, open **Settings**, select **MCP servers**, then **Add server**, fill in the same kind of fields, save, and select **Restart**. ChatGPT web does not read local Codex configuration files or expose the local Codex command menu. Open the **Plugins** tab there to browse and manage available tools. That is a different path from this `config.toml` setup. Installed plugins can bundle MCP servers. Those servers are launched from the plugin, so user config does not set their transport command. User config can still control on/off state and tool policy under `plugins..mcp_servers.`. ## What to do next Run the documented Context7 command, `codex mcp add context7 -- npx -y @upstash/context7-mcp`, then `codex mcp list`. Open the Codex TUI and use `/mcp`. If the server is missing, confirm the table is in `~/.codex/config.toml` or in a trusted project’s `.codex/config.toml`. For an HTTP server, add a `[mcp_servers.]` table with a `url`, and run `codex mcp login ` only when that server expects OAuth. For every other MCP key, use the configuration reference linked from the Codex MCP page rather than a key that page does not list. ## Sources - [Model Context Protocol in Codex](https://developers.openai.com/codex/mcp)