Codex MCP: how to add MCP servers to Codex

Codex can use MCP servers. An MCP server gives Codex tools from another system, such as searching documentation, reading a Linear issue or sending a Slack message, and Codex decides when to call them. You add a server once, and the Codex CLI, the IDE extension and the ChatGPT desktop app all pick it up, because they share one configuration.

This guide covers adding local and remote servers, the config.toml options worth knowing, signing in with OAuth, choosing which tools need your approval, and what to do when a server's tools don't show up. We checked every step on October 29, 2026 with Codex CLI 0.165.0 while connecting Corsair's own MCP server, so the commands and output below are real.

What Codex can do once it reaches your other apps

Setup is the dull part, so here's what it buys you. On October 30 we connected Codex to Corsair on a test account that has a demo Slack workspace and a small GitHub repo, and asked:

Find the open issues in the corsair-review GitHub repository and any messages
in the Corsair Review Slack workspace that discuss them. Then tell me which
issue to fix first and why. Only read data; do not change anything.

Codex made five calls to Corsair: one search across the data Corsair had synced, three read_data calls that read GitHub and Slack live, and one list_operations to look up the GitHub actions it needed. It answered:

Fix #1: Reject non-HTTP(S) URLs first. Slack reports an actual javascript: URL being shortened and redirected, making this an observed security problem. URL validation is also a v0.3 launch requirement.

It ranked the other three issues from the same Slack thread: losing links on restart next, link expiry tied to a future paid tier, and unique visitors deferred until after v0.3. Codex never saw a GitHub or Slack token. For this run we also turned off Corsair's three write tools with disabled_tools, which the config section below covers, so Codex could only read.

The rest of this guide shows how to set that up. Corsair is the example, and any other MCP server works the same way.

What MCP support in Codex covers

Codex works with two kinds of MCP servers:

• Local (STDIO) servers. Codex starts the server on your machine with a command, such as npx -y @upstash/context7-mcp, and can pass it environment variables.
• Remote (Streamable HTTP) servers. Codex connects to a URL. A remote server can take a bearer token or OAuth sign-in, and OpenAI's own servers can use your ChatGPT session.

Codex also reads the instructions a server sends when it connects and treats them as guidance for all of that server's tools.

Servers live in ~/.codex/config.toml. You can also add servers for a single project in that project's .codex/config.toml, which Codex reads only for projects you've marked as trusted.

Add an MCP server from the Codex CLI

codex mcp add writes a server to your config. Give it a name, then either a command or a URL.

A local server

Put the command after --:

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

Add --env KEY=VALUE for each environment variable the server needs. That flag only works for local servers.

A remote server by URL

Use --url. This is what happened when we added Corsair:

$ codex mcp add corsair --url https://mcp.corsair.dev/mcp
Added global MCP server 'corsair'.
Detected OAuth support. Starting OAuth flow…
Authorize `corsair` by opening this URL in your browser:
https://hub.corsair.dev/mcp-auth/authorize?response_type=code&…
Successfully logged in.

Codex saw that the server signs in with OAuth and started the sign-in right away. It opened the authorize page in the browser, waited for the callback on 127.0.0.1, and finished as soon as we approved. When Codex can't tell whether a server needs sign-in, it still adds the server, prints "MCP server may or may not require login" and asks you to run codex mcp login <name>.

The command added two lines to the config file:

[mcp_servers.corsair]
url = "https://mcp.corsair.dev/mcp"

If a remote server takes an API key instead of OAuth, put the key in an environment variable and pass the variable's name with --bearer-token-env-var. Codex sends the key as an Authorization: Bearer header.

Check, sign in again or remove a server

codex mcp list            # every server, whether it's on, and how it signs in
codex mcp get corsair     # one server's settings (add --json for JSON)
codex mcp login corsair   # sign in again, for example after a sign-in expires
codex mcp logout corsair  # delete the stored sign-in
codex mcp remove corsair  # remove the server from your config

For remote servers, codex mcp list has an Auth column. It shows OAuth when you're signed in, Bearer token when the server uses one, Not logged in when an OAuth server still needs codex mcp login, and Unsupported for servers that don't use OAuth.

Configure MCP servers in config.toml

Editing the file gives you every option. Each server is a [mcp_servers.<name>] table:

# A remote server that signs in with OAuth
[mcp_servers.corsair]
url = "https://mcp.corsair.dev/mcp"
tool_timeout_sec = 120

# A local server started with a command
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

# A remote server that reads its token from your environment
[mcp_servers.example]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "EXAMPLE_TOKEN"

Local servers take command, plus optional args, env for fixed values, env_vars for variables passed through from your shell, and cwd.

Remote servers take url, plus optional bearer_token_env_var, http_headers for fixed headers, env_http_headers for headers read from environment variables, and http_headers_helper, a command that prints headers as JSON.

Both kinds take these:

• startup_timeout_sec: how long the server gets to start. The default is 10.
• tool_timeout_sec: how long one tool call can run. The default is 60, so raise it for servers that run long jobs.
• enabled = false turns a server off without deleting it.
• required = true stops Codex from starting if that server can't.
• enabled_tools and disabled_tools limit which of the server's tools Codex sees.

Keep secrets out of URLs and fixed headers. codex mcp list prints every server's URL in full, so a key in a query string ends up in your terminal and in anything you paste it into. Use bearer_token_env_var or env_http_headers instead.

Choose which MCP tools need your approval

default_tools_approval_mode sets how Codex treats one server's tools. It takes auto, prompt, writes or approve. OpenAI documents one of them precisely: writes asks before any tool the server hasn't marked read-only, and runs read-only tools without asking.

That makes writes a good fit for servers that mark their tools carefully. You can also override a single tool with tools.<tool>.approval_mode. OpenAI's own example sets a server to prompt and one of its tools to approve. For Corsair, writes is the setting to start with:

[mcp_servers.corsair]
url = "https://mcp.corsair.dev/mcp"
default_tools_approval_mode = "writes"

Corsair marks list_integrations, list_operations, get_schema, search, read_data and view_routines read-only. With writes, Codex runs those without asking. It asks before the three that change something: get_connect_link, which adds an app, update_routine, which sets up automations, and run_script, which can send, create, update or delete things in your apps.

Use MCP servers in the Codex app, IDE extension and terminal

The ChatGPT desktop app, the Codex CLI and the IDE extension share the same MCP configuration, so a server you add in one shows up in the others.

• ChatGPT desktop app. Open Settings > MCP servers, select Add server, enter a name, choose STDIO or Streamable HTTP, and give the command or URL. Save, then select Restart. Servers that need OAuth show an Authenticate button.
• IDE extension. Open the gear menu > MCP servers and add the server the same way, then select Restart extension.
• Terminal (TUI). Type /mcp in a Codex session to see your active servers.

How Codex signs in to MCP servers

When a remote server uses OAuth, Codex has to register itself as a client first. It does that in one of two ways:

• Client ID Metadata Document (CIMD). Codex identifies itself with a document OpenAI hosts. Codex picks this when the server says it supports CIMD.
• Dynamic Client Registration (DCR). Codex registers a new client with the server as you sign in. This is the fallback, and most servers support it.

Corsair supports DCR, so Codex registered itself on the spot. Our sign-in screen says so: "The app chose its own name; Corsair hasn't verified it." That's what DCR implies for any server, and it's why the screen asks you to allow it only if you just started connecting from an app on your computer.

A few login options help in less common setups:

• codex mcp login <name> --no-browser prints the authorize URL and lets you paste the callback URL back. Use it on a remote machine or over SSH.
• --oauth-client-registration cimd or dcr forces one method for a single login.
• --oauth-client-id, with --oauth-client-secret for confidential clients, on codex mcp add uses a client you registered yourself.
• mcp_oauth_callback_port in config.toml fixes the local callback port, for providers that need an exact redirect URI.
• mcp_oauth_credentials_store chooses where sign-ins are stored: auto, file or keyring.

Troubleshooting Codex MCP

• A server is listed, but Codex says its tools aren't available. This happened to us. Codex waits one second for servers to start before it builds its tool list, and a server that takes longer is left out of that list. Our first codex exec run reported that Corsair's list_integrations tool "isn't available in this session". Setting mcp_optional_startup_grace_ms = 0 in config.toml makes Codex wait for each server's full startup_timeout_sec, and the same run then called the tool. Marking the server required = true has the same effect for that one server.
• "Not logged in" in codex mcp list. Run codex mcp login <name>.
• The server times out on start. Raise startup_timeout_sec. Local servers started with npx can take a while on the first run while the package downloads.
• Long tool calls stop at 60 seconds. Raise tool_timeout_sec for that server.
• Servers in a project's .codex/config.toml are ignored. Codex reads project config only for trusted projects.

One MCP server for every app: Corsair in Codex

Adding a server per app works until you need several. Each one is its own sign-in, its own tokens in your config and its own set of tools in Codex's context.

Corsair is one remote MCP server, at https://mcp.corsair.dev/mcp, for the apps you connect to it, such as Gmail, Slack, GitHub, Linear, Notion and about 400 more. You add it to Codex once, as shown above. App credentials stay encrypted in Corsair, so they never go into a prompt or your config.toml.

Each connection uses a link with a mode, and Corsair checks every action against it, whatever Codex allows:

• Read. Reads only. Writes are refused.
• Cautious. The default. Writes go through, and anything destructive, such as a delete, waits for your approval.
• Strict. Every write needs approval, and destructive actions are refused.
• Open. Everything runs without asking.

That works alongside Codex's own approvals: you can set Corsair to writes in config.toml and still have Corsair refuse deletes on a Strict link. Corsair can also set up automations that run on a schedule or when an app sends an event, and Codex can check how each run went.

Each app has its own page listing what Codex can do with it, for example the Linear MCP server. Setup for Codex and every other client is in Corsair's MCP docs.

FAQs

Does Codex support MCP?

Yes. The Codex CLI, the IDE extension and the ChatGPT desktop app all support MCP servers, both local servers started with a command and remote servers reached by URL, and they share one configuration.

How do I add an MCP server to Codex?

Run codex mcp add <name> -- <command> for a local server or codex mcp add <name> --url <url> for a remote one. You can also add a [mcp_servers.<name>] table to ~/.codex/config.toml, or use Settings > MCP servers in the ChatGPT desktop app.

Where is the Codex MCP config file?

In ~/.codex/config.toml, under [mcp_servers.<name>] tables. A project can also have its own .codex/config.toml, which Codex reads only when the project is trusted.

Does Codex support remote MCP servers with OAuth?

Yes. When you add a remote server that uses OAuth, Codex usually starts the sign-in right away and registers itself with the server through CIMD or Dynamic Client Registration. Run codex mcp login <name> to sign in again later.

Can I add an MCP server to one project only?

Yes. Put the server in that project's .codex/config.toml. Codex reads project config only for projects you've marked as trusted.

Why don't my MCP server's tools show up in Codex?

The server may still be starting when Codex builds its tool list, because Codex waits one second by default. Set mcp_optional_startup_grace_ms = 0 or mark the server required = true, then check /mcp and codex mcp list for its status and sign-in.

Do the Codex CLI and the IDE extension share MCP servers?

Yes. The CLI, the IDE extension and the ChatGPT desktop app read the same MCP configuration, so a server added in one is available in the others.