How to connect Codex to an MCP server

Model Context Protocol connects models to tools and context. Use it to give ChatGPT or Codex access to third-party documentation, or to let it interact with developer tools such as a browser or Figma. Local Codex clients can connect directly to MCP servers and share their configuration. The ChatGPT desktop app, the Codex CLI, and the IDE extension support MCP servers and share MCP configuration for the same Codex host. Once the server is configured, you can switch among those clients without redoing setup.

ChatGPT on the web does not read local Codex configuration files or expose the local Codex command menu. It can use remote MCP-backed tools supplied by plugins. Hosted plugin tools can have different capabilities from MCP servers configured on a Codex host. This guide stays on a local stdio server: a process started by a command and stored in config.toml.

Where Codex stores the server

Codex stores MCP configuration in config.toml alongside other Codex configuration settings. By default this is ~/.codex/config.toml. You can also scope MCP servers to a project with .codex/config.toml. That project file applies only for trusted projects. The desktop app, CLI, and IDE extension share this configuration.

A stdio server runs as a local process that Codex starts with a command. Environment variables are a supported feature for that process. Codex also supports streamable HTTP servers that you access at an address, including bearer token authentication and OAuth. The CLI example on the MCP page is the stdio form. In the desktop app and the IDE extension, choose STDIO or Streamable HTTP and provide a command or URL.

Codex reads the MCP instructions field returned during initialization and uses it as server-wide guidance alongside the server's tools. If you maintain the server, use instructions for cross-tool workflows, constraints, and rate limits that apply across the server. Keep the first 512 characters self-contained so the most important guidance is available when Codex is deciding how to use the server.

Add a stdio server with the CLI

The documented add command takes a server name, optional repeated --env assignments, then -- and the command that starts the local process. The worked example is Context7, a free MCP server for developer documentation. It sets no environment variables:

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

The page does not list Context7 environment variables, so do not invent any. If your own server needs variables, copy the --env form from the add command on the MCP page, or from codex mcp --help, instead of guessing names.

Run codex mcp list to see configured servers. Run codex mcp --help to see all available MCP commands. For a server that supports OAuth, run codex mcp login <server-name>. The Context7 example does not include a login step.

Confirm the server

In the codex TUI, use /mcp to see your active MCP servers. In the ChatGPT desktop app composer, type /mcp to view connected servers.

You do not add the server a second time if the CLI or config.toml already has it. Use a menu only when you would rather create the entry there.

In the IDE extension:

Open the gear menu, then select MCP servers.
Select Add server.
Enter a name, choose STDIO or Streamable HTTP, and provide the server's command or URL.
Save the server, then select Restart extension.

The MCP server list shows which servers are enabled and which require OAuth. Select Authenticate when an OAuth server requires sign-in.

The desktop app uses the same shape:

Open Settings, then select MCP servers.
Select Add server.
Enter a name, choose STDIO or Streamable HTTP, and provide the server's command or URL.
Save the server, then select Restart.

That list also shows which servers are enabled and which require OAuth. Select Authenticate when an OAuth server requires sign-in.

Write the stdio server in config.toml

For more fine-grained control, edit ~/.codex/config.toml or a project-scoped .codex/config.toml. The configuration reference is the searchable list of every supported MCP option. The MCP page documents these stdio fields:

command (required): the command that starts the server.
args (optional): arguments to pass to the server.
env (optional): environment variables to set for the server.
env_vars (optional): environment variables to allow and forward.
cwd (optional): working directory to start the server from.
experimental_environment (optional): set to remote to start the stdio server through a remote executor environment when one is available.

The documented Context7 table splits the same npx invocation into command and args, and shows sample environment fields:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"

The page presents this as a config example. It does not say that the add command writes these exact lines. LOCAL_TOKEN and MY_ENV_VAR are sample names. Omit those lines, or replace the names with ones your server documents.

env_vars can contain plain variable names or objects with a source:

env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]

String entries and source = "local" read from Codex's local environment. source = "remote" reads from the remote executor environment and requires remote MCP stdio.

Timeouts, enablement, and which tools run

The same server table accepts optional controls documented on the MCP page. startup_timeout_sec is the timeout in seconds for the server to start. Default: 10. tool_timeout_sec is the timeout in seconds for the server to run a tool. Default: 60. Set enabled to false to disable a server without deleting it. Set required to true to make startup fail if this enabled server cannot initialize.

enabled_tools is a tool allow list. disabled_tools is a tool deny list, applied after enabled_tools. default_tools_approval_mode sets the default approval behavior for tools from this server. Supported values are auto, prompt, writes, and approve. The writes mode prompts for tools that are not marked read-only. The page also documents a per-tool approval_mode and a per-tool output_token_limit: a positive budget for one tool's output, before the standard 20% serialization allowance, which overrides the model's default output truncation budget for that tool.

The top-level mcp_optional_startup_grace_ms setting controls how long Codex waits for optional MCP servers when building the initial tool catalog. It defaults to 1000 milliseconds. Set it to 0 to wait for each server's startup_timeout_sec instead. Required servers still use their startup timeouts.

The MCP page does not say that saving config.toml reloads an already running TUI session. The IDE steps do say to restart the extension after you save a server.

What to do next

Add Context7 with the documented command above, then open the Codex TUI and use /mcp. If you need a working directory, a tool allow list, or an approval policy, put those keys in the server table instead of guessing extra CLI flags. For the full add syntax and any management command this page does not spell out, run codex mcp --help and follow that output.

Sources

Codex MCP