How to Add a Remote MCP Server to Codex
A practical guide to adding a remote MCP server to OpenAI Codex: CLI and config.toml setup, bearer token, API key header, and OAuth authentication, tool filtering, timeouts, and troubleshooting.

Kelis Shekhaliya

TL;DR
To add a remote MCP server to Codex, run <code>codex mcp add <name> --url <url></code> or add a <code>[mcp_servers.<name>]</code> table with a <code>url</code> to <code>~/.codex/config.toml</code>. Keep tokens in environment variables with <code>bearer_token_env_var</code> or <code>env_http_headers</code>, sign in to OAuth servers with <code>codex mcp login</code>, and confirm with <code>codex mcp list</code> and a read-only tool call.
To add a remote MCP server to Codex, add a [mcp_servers.<name>] table with the server's url to ~/.codex/config.toml, or run codex mcp add <name> --url <url>. If the server takes an API key or bearer token, point bearer_token_env_var at an environment variable instead of writing the token into the file. If it uses OAuth, run codex mcp login <name>. Then run codex mcp list to confirm the server loaded, and ask Codex for a small read-only task that needs one of its tools.
This guide is for SaaS founders, CTOs, and API teams who run an MCP server, or are about to, and want developers to use it from OpenAI Codex. It covers where Codex reads its MCP configuration, the CLI and TOML setup, each authentication option, how to limit which tools Codex sees, and what to check when a server will not connect.
Why Codex matters for a SaaS MCP server
Codex is OpenAI's coding agent, and it can call MCP tools while it works. When your API is available as an MCP server, a developer can ask Codex to look up records, create test data, or check the state of an integration in your product without switching to a dashboard or pasting responses into the chat.
One detail makes Codex convenient to support: the Codex CLI, the Codex IDE extension, and the ChatGPT desktop app share the same MCP configuration for the same Codex host. A server you add once is available in all three. If you also support other coding tools, see how to add a remote MCP server to Claude Code and how to add a remote MCP server to VS Code.
Before you start
The server has a reachable URL. A remote server is added by its MCP endpoint, such as
https://mcp.example.com/mcp, not by the product's homepage.It speaks Streamable HTTP. Codex supports two kinds of MCP server: STDIO servers that run as a local process, and Streamable HTTP servers that you reach at an address. A hosted server is the second kind.
You know the authentication method. No authentication, a bearer token, another header such as an API key header, or OAuth. Each one changes the configuration.
The tools are tested. Confirm that tool discovery and a few calls work before you hand the setup to anyone. Our guide to testing an MCP server with MCP Inspector covers this.
One naming trap: codex mcp manages the MCP servers Codex connects to, which is what this guide covers. codex mcp-server does the opposite and runs Codex itself as an MCP server for another client.
Where Codex reads MCP configuration
Codex stores MCP servers in config.toml, next to its other settings. There are two scopes:
| Scope | File | Use it for |
|---|---|---|
| User | ~/.codex/config.toml | Servers you use across every project |
| Project | .codex/config.toml in the project | Servers tied to one codebase; only read for trusted projects |
Each server is one table named [mcp_servers.<name>]. The name is how you refer to the server in commands such as codex mcp login, so keep it short and stable. When you add a server, merge the new table into the existing file. Do not replace the whole file, and if a table with the same name already exists, update it instead of adding a duplicate.
Add the server
With the CLI
The quickest way is one command:
codex mcp add my-api --url https://mcp.example.com/mcpIf the server takes a bearer token, add the name of the environment variable that holds it:
codex mcp add my-api --url https://mcp.example.com/mcp --bearer-token-env-var MY_API_TOKENRun codex mcp list to see configured servers, codex mcp remove my-api to delete one, and codex mcp --help for the full set of commands.
With config.toml
For more control, edit the file directly. The only required key for a remote server is url:
[mcp_servers.my-api]
url = "https://mcp.example.com/mcp"With the ChatGPT desktop app or the IDE extension
In the ChatGPT desktop app, open Settings, select MCP servers, then Add server. In the Codex IDE extension, open the gear menu, select MCP servers, then Add server. Enter a name, choose Streamable HTTP, paste the URL, save, and restart when prompted. Because the configuration is shared, the server then appears in the CLI as well.
Set up authentication
Bearer token or API key in the Authorization header
Use bearer_token_env_var. Codex reads the named environment variable and sends its value as Authorization: Bearer ...:
[mcp_servers.my-api]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "MY_API_TOKEN"Set the variable in the environment Codex starts from, for example export MY_API_TOKEN="..." in your shell profile, then start Codex again.
An API key in another header
If the server expects a header such as X-Api-Key, use env_http_headers, which maps header names to environment variable names. http_headers takes fixed values and suits non-secret headers only:
[mcp_servers.my-api]
url = "https://mcp.example.com/mcp"
http_headers = { "X-Client" = "codex" }
env_http_headers = { "X-Api-Key" = "MY_API_KEY" }Use the environment-variable forms for anything secret, especially in a project's .codex/config.toml, which is often committed to the repository. For more on choosing between these methods on the server side, see MCP API authentication.
OAuth
For a server that supports OAuth, add it with just the URL and run:
codex mcp login my-apiCodex opens a browser for sign-in and stores the credentials. On a machine without a local browser, run codex mcp login my-api --no-browser, open the printed URL elsewhere, sign in, and paste the full redirect URL back into the terminal. Codex supports OAuth with Dynamic Client Registration and Client ID Metadata Documents, so most servers need no extra setup.
If your authorization server only accepts pre-registered clients, pass the client ID when you add the server, and register the exact callback URL that codex mcp add prints:
codex mcp add my-api --url https://mcp.example.com/mcp --oauth-client-id my-clientFor a confidential client, also pass --oauth-client-secret and read the value from an environment variable. Codex saves that secret in config.toml, so keep the file private and out of version control.
Control which tools Codex sees, and how long they run
A few optional keys make a server easier to use well:
enabled_toolsis an allow list of tool names, anddisabled_toolsis a deny list applied after it. A shorter, focused list makes it easier for the model to pick the right tool.default_tools_approval_modesets how Codex asks before calling tools:auto,prompt,writes, orapprove. Thewritesmode prompts for tools that are not marked read-only, which is a sensible default for an API that can change data.startup_timeout_sec(default 10) andtool_timeout_sec(default 60) control how long Codex waits for the server to start and for one tool call.enabled = falseswitches a server off without deleting its configuration.
[mcp_servers.my-api]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "MY_API_TOKEN"
disabled_tools = ["delete_project"]
default_tools_approval_mode = "writes"
tool_timeout_sec = 120If you maintain the server, Codex also reads the MCP instructions field returned during initialization and uses it as server-wide guidance. OpenAI recommends keeping the first 512 characters self-contained, so put the most important rules for using your tools there.
Test the connection
Run codex mcp list, or type /mcp in the Codex terminal UI, to confirm the server is configured and active. Then ask for a low-impact task that needs one of its tools, and name the server so the test is clear:
Use the my-api MCP tools to list my three most recent projects. Do not change anything.Check that the tool call appears in the session and returns real data. A plausible answer with no tool call does not verify the connection. Start with a read-only tool before anyone tries a write.
Troubleshooting
The server is not listed
Check that the table is in a file Codex reads: ~/.codex/config.toml, or .codex/config.toml in a project you have marked as trusted. Confirm the table name starts with mcp_servers. and that the TOML is valid, then restart Codex or reopen your IDE session.
Authentication fails
If you use bearer_token_env_var or env_http_headers, the value must be set in the environment Codex was started from. A variable exported in another terminal, or added after Codex started, is not seen. For OAuth servers, run codex mcp login <name> again. Also check the URL path: many servers serve MCP at /mcp, not at the root.
A tool call times out
Tool calls stop at 60 seconds by default. Raise tool_timeout_sec for a slow tool. If a server is slow to start, raise startup_timeout_sec.
It works locally but not in a cloud task
The CLI and IDE extension connect from your machine, so they can reach hosts on your network or VPN. OpenAI notes that local MCP servers and transports may not be available in the cloud, so check connectivity and authentication separately for remote runs. A publicly reachable HTTPS endpoint avoids most of these problems.
The server connects but its tools are not used
Codex chooses tools from their names and descriptions. Check that the tools are not filtered out by enabled_tools or disabled_tools, then look at the tools themselves: clear names, precise descriptions, and a focused set make the right choice easier.
Adding a 0mcp server to Codex
If your MCP server is hosted on 0mcp, you do not need to write the entry from scratch. Publish a server version, open Setup, and select Codex. 0mcp gives you both a ready CLI command and a TOML block. Choose the user or project scope, set every environment variable 0mcp lists before starting Codex, merge the block into your existing config.toml, then restart Codex and confirm the server appears in the MCP list. The 0mcp Codex setup guide has the details.
Final checklist
The server URL is public and serves Streamable HTTP.
The server is a
[mcp_servers.<name>]table in~/.codex/config.tomlor a trusted project's.codex/config.toml.Secrets come from
bearer_token_env_var,env_http_headers, or OAuth, never from committed files.OAuth servers have been signed in with
codex mcp login.Unneeded or risky tools are filtered, and write tools prompt for approval.
codex mcp listshows the server, and a read-only tool call returns real data.
FAQ
01How do I add a remote MCP server to Codex?+-
Run <code>codex mcp add <name> --url <url></code>, or add a <code>[mcp_servers.<name>]</code> table with a <code>url</code> key to <code>~/.codex/config.toml</code>. Then run <code>codex mcp list</code> to confirm it loaded and test a read-only tool call.
02Where is the Codex MCP config file?+-
By default it is <code>~/.codex/config.toml</code>. You can also scope servers to one project with <code>.codex/config.toml</code>, which Codex reads only for trusted projects. The Codex CLI, IDE extension, and ChatGPT desktop app share this configuration.
03How do I pass an API key to an MCP server in Codex?+-
For a bearer token, set <code>bearer_token_env_var</code> to the name of an environment variable and Codex sends it as <code>Authorization: Bearer ...</code>. For another header, use <code>env_http_headers</code> to map the header name to an environment variable. Do not write literal keys into the file.
04Does Codex support OAuth for remote MCP servers?+-
Yes. Run <code>codex mcp login <name></code> to sign in. Codex supports Dynamic Client Registration and Client ID Metadata Documents, and for servers that need a pre-registered client you can pass <code>--oauth-client-id</code> when adding the server.
05Why does my MCP tool call time out in Codex?+-
Codex waits 60 seconds for a tool call and 10 seconds for a server to start by default. Raise <code>tool_timeout_sec</code> or <code>startup_timeout_sec</code> in the server's table if your tools or server need longer.
06What is the difference between codex mcp and codex mcp-server?+-
<code>codex mcp</code> manages the MCP servers Codex connects to. <code>codex mcp-server</code> runs Codex itself as an MCP server so another client can call it.