Connecting MCP Servers to Codex

Who this is for and what you will get

If you want Codex to reach your team's ticketing system, a documentation site or a browser tool, you need to connect an MCP server. This guide shows you how to add one from the command line or from a configuration file, check that it is connected, handle OAuth sign-in, and limit which tools Codex can call.^[1]

What MCP does in Codex

The Model Context Protocol (MCP) lets Codex use tools and information from other systems. An MCP server lists the tools it offers and handles the requests Codex sends, such as looking up a ticket or fetching documentation.^[1]

Codex supports two kinds of server. A STDIO server runs as a local process that a command starts. A Streamable HTTP server is reached at an address.^[1] The desktop app, the CLI and the IDE extension all read the same MCP configuration for a Codex host, so you set it up once and switch between clients without repeating the work.^[1]

Where the configuration lives

The configuration file is ~/.codex/config.toml by default. To scope a server to one project, put it in that project's .codex/config.toml. Project-scoped configuration only applies to trusted projects.^[1]

Add a server from the command line

To add a STDIO server, run codex mcp add with a name, any --env pairs, and the start command after --:

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

For example, Context7 is a free MCP server for developer documentation. Add it like this:^[1]

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

Run codex mcp list to see the servers you have configured. In the terminal interface, /mcp shows the servers that are active.^[1]

Add a server in the app or the IDE

In the desktop app, open Settings and select MCP servers. Choose Add server, pick STDIO or Streamable HTTP, enter the command or URL, save, and select Restart. Typing /mcp in the composer lists the connected servers.^[1]

In the IDE extension, open the gear menu, select MCP servers and Add server, then enter the name, transport and address. Save, and select Restart extension.^[1]

Configure servers in config.toml

Each server gets its own [mcp_servers.<server-name>] table. The reference page lists every supported option.^[1] For a STDIO server, command is required; args, env, env_vars and cwd are optional.^[1] This entry starts Context7 with a value set in its environment:

[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_vars accepts plain names as well as objects that name a source. Plain names and source = "local" read from Codex's local environment. source = "remote" reads from the remote executor and works only with remote STDIO servers.^[1]

For a Streamable HTTP server, url is required. bearer_token_env_var names the environment variable that holds a bearer token, and http_headers sets static headers. env_http_headers pulls header values from environment variables.^[1] The auth field defaults to oauth, which uses stored MCP OAuth credentials. Setting it to chatgpt uses the current ChatGPT session for the trusted ChatGPT origin and keeps stored OAuth as a fallback.^[1]

http_headers_helper points to a local command that prints a JSON object of headers. It works only for HTTP servers reached from the local machine, not for STDIO servers or remote execution. Codex caches the headers. After a POST to the same origin returns 401 or 403, it refreshes them once and retries only if the values have changed.^[1]

Timeouts and enabling

startup_timeout_sec defaults to 10 seconds and tool_timeout_sec defaults to 60 seconds. Set enabled = false to turn a server off without deleting its entry.^[1] Setting required = true makes startup fail if the server is not ready. The default startup_readiness value, "connection", needs a live connection. The value "catalog" lets a valid cached tool catalog satisfy startup, but tool calls still need a live connection.^[1]

The top-level mcp_optional_startup_grace_ms setting defaults to 1000 milliseconds. It controls how long Codex waits for optional servers while it builds the initial tool list. Set it to 0 to wait for each server's full startup timeout. Required servers always use their own timeouts.^[1]

Limit which tools Codex can use

enabled_tools is an allow list. disabled_tools is a deny list that is applied after it. default_tools_approval_mode accepts auto, prompt, writes or approve, and writes asks for approval on tools that are not marked read-only.^[1] For one tool, tools.<tool>.approval_mode overrides approval, and tools.<tool>.output_token_limit caps the tool's output in tokens.^[1] A Streamable HTTP server that uses these options looks like this:

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"] # applied after enabled_tools
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"
output_token_limit = 30000

Sign in to OAuth servers

For a server that uses OAuth, run codex mcp login <server-name>. On a machine without a local browser, add --no-browser. Open the authorization URL the command prints, sign in, and paste the full redirect URL back into the terminal. Do this even if the browser cannot load the callback page.^[1]

If the authorization server needs a pre-registered client, pass its ID when you add the server:

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client

A confidential client also needs --oauth-client-secret. Codex writes that secret into config.toml under mcp_servers.example.oauth.client_secret, so keep the file private and out of version control.^[1] Register the exact callback URL that codex mcp add prints. Use mcp_oauth_callback_url or mcp_oauth_callback_port only when you need a custom callback.^[1] To set scopes, use mcp_servers.<server-name>.scopes in the config file, or pass --scopes to codex mcp login for a single login.^[1]

Examples of servers to try

The documentation names OpenAI Docs MCP, Context7, Figma, Playwright, Chrome DevTools, Sentry and GitHub as common examples.^[1]

Common problems

Startup is slow or fails. Raise startup_timeout_sec, or set mcp_optional_startup_grace_ms to 0 so Codex waits for the full timeout.^[1]
Tool calls time out. Raise tool_timeout_sec for that server.^[1]
You want Codex to ask before using a tool. Set default_tools_approval_mode to prompt, or set approval_mode for that tool.^[1]