How to Add a Remote MCP Server to OpenAI Codex

How do I add a remote MCP server to Codex?

Run one command:

codex mcp add my-server --url https://mcp.example.com/mcp

If the server needs OAuth, finish with:

codex mcp login my-server

That writes an [mcp_servers.my-server] block to ~/.codex/config.toml — the same file every Codex surface reads. This is the entire setup for a server that doesn't require a credential up front.

Configuring by file instead

Codex reads remote MCP servers from ~/.codex/config.toml (global, available to every Codex install on the machine) or a project-local .codex/config.toml (scoped to one project). Open the file in your editor — create it if it doesn't exist — and add:

[mcp_servers.my-server]
url = "https://mcp.example.com/mcp"

Save, then fully quit Codex (Cmd-Q on Mac, not just close the window) and reopen.

A project-local .codex/config.toml only loads for projects you've marked trusted. If a project-scoped server seems to be ignored, check the project's trust setting before anything else.

Authenticating: bearer token or OAuth

Remote MCP servers authenticate one of two ways in Codex.

Bearer token, via an environment variable:

[mcp_servers.my-server]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "MY_SERVER_TOKEN"

The _env_var suffix means put the variable's name here, not the token itself. Codex reads MY_SERVER_TOKEN from the shell environment at connect time and sends it as an Authorization: Bearer header — the token itself never lives in config.toml. Export the variable in the shell profile that launches Codex (export MY_SERVER_TOKEN=...), then restart Codex.

Codex also supports static or environment-sourced custom headers, for servers that expect something other than a bearer token:

[mcp_servers.my-server]
url = "https://mcp.example.com/mcp"
http_headers = { "X-Custom-Header" = "value" }

OAuth, when the server supports it:

codex mcp login my-server

A browser window opens with the server's consent screen. Sign in if prompted, review the requested scopes, and approve. Codex stores the access token locally and reuses it on future sessions. If the browser doesn't open, Codex prints the authorization URL in the terminal so you can open it yourself.

The CLI command in full

codex mcp add my-server --url https://mcp.example.com/mcp

Add a bearer token in the same step:

codex mcp add my-server --url https://mcp.example.com/mcp --bearer-token-env-var MY_SERVER_TOKEN

This writes the same [mcp_servers.my-server] block that hand-editing config.toml would produce. If a flag errors on an older build, run codex mcp add --help or edit config.toml directly.

Shared across every Codex surface

Codex ships as a CLI, an IDE extension (VS Code, Cursor, and similar), and a tab inside the ChatGPT desktop app. All three read the same ~/.codex/config.toml. Add a server from any one of them — the terminal, the extension's settings panel, or the desktop app's MCP settings form — and it shows up in the others without redoing setup.

• IDE extension: open the extension's settings panel → MCP settings → Open config.toml. It opens the same file described above.
• ChatGPT desktop app: Settings → MCP servers → Add server, and fill in the form. The app writes the same TOML block for you.

If a desktop-app form seems to fail silently — the OAuth window closes immediately, or the server never appears — edit config.toml directly instead; the same block applies, and the app picks it up on next launch.

Listing and verifying servers

codex mcp list

shows every configured server and its status. Inside a Codex session, run /mcp to see active servers without leaving the conversation. In the desktop app or IDE extension, the same list appears under Settings → MCP servers, showing each server as connected, disconnected, or awaiting OAuth.

To confirm end to end, start a new Codex session and ask what tools it has access to. If the server's tools are listed, you're connected.

Timeouts

Two per-server settings control how long Codex waits on a remote server:

[mcp_servers.my-server]
url = "https://mcp.example.com/mcp"
startup_timeout_sec = 10
tool_timeout_sec = 60

• startup_timeout_sec — how long Codex waits for the server to initialize when a session starts. Default is 10 seconds; raise it if your server is slow to respond to the first handshake.
• tool_timeout_sec — how long Codex waits for any single tool call to return. Default is 60 seconds; raise it for a server whose tools run long queries or jobs.

A top-level mcp_optional_startup_grace_ms setting (default 1000ms) gives non-required servers a short extra grace period during startup without blocking the session.

Other per-server options

• enabled = false — keep a server's configuration in the file but skip loading it, without deleting the block.
• required = true — fail Codex's startup if this specific server doesn't initialize, instead of continuing without it.
• enabled_tools / disabled_tools — allow- or deny-list specific tools from a server, if you want to expose only part of what it offers.

What usually goes wrong

Problem	Fix
Bearer token server won't connect	Check bearer_token_env_var holds the variable's name, not the token value, and that the variable is exported in the shell that launched Codex
A project-local .codex/config.toml seems to be ignored	Codex only loads project-scoped config for projects marked trusted. Trust the project, or use the global file
Browser doesn't open during codex mcp login	Codex prints the authorization URL in the terminal — copy it into your browser manually
Tools list doesn't update after a server-side change	Restart Codex, or remove and re-add the server, to force it to refetch the tool list
Server takes long to respond on first connect	Raise startup_timeout_sec for that server's block

A worked example

With a real server — Tempreon, a hosted MCP server that gives your coding sessions a persistent memory of your architecture decisions and conventions — the setup looks the same as any other remote MCP server:

codex mcp add tempreon --url https://api.tempreon.com/functions/v1/tempreon-mcp/mcp
codex mcp login tempreon

Then confirm with codex mcp list. The full account-holder walkthrough, including where to find your server URL, is in the Codex setup doc.