How to add an MCP server to Codex: CLI, config.toml and IDE

Codex can call tools from any Model Context Protocol (MCP) server you connect: documentation search, a browser, an issue tracker, or your own internal API. Adding one takes a single codex mcp add command or a few lines in config.toml, and the same setup works in the terminal, the IDE extension and the desktop app.

What an MCP server does in Codex

An MCP server gives Codex extra tools it can call while it works. Codex supports two kinds: stdio servers, which run as a local process started by a command, and Streamable HTTP servers, which you reach at a URL. Codex also reads the instructions a server returns when it connects and treats them as guidance for using that server’s tools.

Add a remote (Streamable HTTP) server

Use codex mcp add with --url to register a server that already runs somewhere.

codex mcp add <server-name> --url https://mcp.example.com/mcp

The same entry in ~/.codex/config.toml looks like this:

[mcp_servers.example]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "EXAMPLE_MCP_TOKEN"

bearer_token_env_var names an environment variable whose value Codex sends in the Authorization header. Leave it out for servers that use OAuth. For other headers, http_headers sets static values and env_http_headers reads values from environment variables.

Add a local (stdio) server

Put -- after the server name; everything after it is the command that starts the server. The Codex docs use Context7, a documentation server, as the example:

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

Pass environment variables with --env, once per variable:

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

In config.toml, a stdio server uses command (required), args, env, env_vars (names of variables to forward from your environment) and cwd:

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

Where Codex keeps MCP configuration

Codex stores MCP servers in ~/.codex/config.toml by default, or in .codex/config.toml inside a project to scope a server to that project.

File	Applies to	Note
~/.codex/config.toml	Every project on your machine	Default target of codex mcp add
.codex/config.toml	One project	Loaded only for trusted projects

Each server is a [mcp_servers.<server-name>] table. Options that apply to both kinds of server:

Key	What it does
enabled	Set false to switch a server off without deleting it
startup_timeout_sec	Seconds to wait for the server to start, default 10
tool_timeout_sec	Seconds to wait for a tool call, default 60
enabled_tools, disabled_tools	Allow list and deny list of tool names
required	Set true to make startup fail if the server is not ready

Sign in to an OAuth server

Run codex mcp login with the server’s name; Codex opens your browser for the sign-in and stores the credentials.

codex mcp login <server-name>

If no credentials are configured, Codex may connect without authentication, so run the login yourself rather than waiting for a prompt. On a machine without a local browser, add --no-browser: Codex prints an authorization URL, you sign in elsewhere and paste the full redirect URL back into the terminal. To request specific scopes for one login, add --scopes read,write. If the provider requires a pre-registered client, pass --oauth-client-id (and --oauth-client-secret for a confidential client) to codex mcp add.

Add a server in the IDE extension or the desktop app

Both have a form for the same fields. In the IDE extension, open the gear menu, select MCP servers, then Add server. Enter a name, choose STDIO or Streamable HTTP, and enter the command or URL. Save, then select Restart extension. In the ChatGPT desktop app the path is Settings, MCP servers, Add server, then Restart. For OAuth servers, select Authenticate in the server list.

Check that it works

codex mcp list shows every configured server, and /mcp in the codex terminal UI shows the active ones.

codex mcp list

Then ask Codex in a session which tools it has from that server. codex mcp --help lists the other MCP subcommands.

Troubleshooting

Most problems come down to the server name, the project trust setting or a timeout:

• The server is missing from the list. Check the [mcp_servers.<server-name>] header for typos. A server in a project’s .codex/config.toml loads only if the project is trusted.
• codex mcp login cannot find the server. The name must match the table name exactly; codex mcp list shows the names Codex knows.
• A local server fails to start in time. Raise startup_timeout_sec, especially for npx servers that download a package on first run.
• Long tool calls fail. Raise tool_timeout_sec for that server.
• Too many tools in the session. Trim them with enabled_tools or disabled_tools.

Example: add Hallway Test to Codex

Hallway Test is a remote MCP server with OAuth, so it needs two commands and no token. It lets your agent send a flow it just built to a real person from our in-house team, who runs it while thinking aloud; see what the usability testing MCP does.

codex mcp add hallwaytest --url https://mcp.hallwaytest.ai/mcp
codex mcp login hallwaytest

Or add the entry by hand:

[mcp_servers.hallwaytest]
url = "https://mcp.hallwaytest.ai/mcp"

The login opens your browser: sign in with Google and approve the connection. codex mcp list then shows hallwaytest, and its tools, among them create_usability_task, are available in every Codex session. A new account can connect right away, but the first request to dispatch a test answers with a link to book the free pilot call. After the 30-minute call we activate the account, with no need to reconnect, and results come back within 24 hours. After public launch a test costs $29. The full walkthrough, including the IDE extension, is on Connect Hallway Test to Codex.

Sources

1. Model Context Protocol, OpenAI Codex documentation
2. Configuration reference, OpenAI Codex documentation