How to connect Codex to an MCP server

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.<server-name>] 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 <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>

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 <server-name>. 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.<server-name>], 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 <server-name>. On a terminal without a local browser, run codex mcp login <server-name> --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.<tool>.approval_mode and tools.<tool>.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.<plugin>.mcp_servers.<server>.

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.<server-name>] table with a url, and run codex mcp login <server-name> 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