How to add an MCP server to Codex

TL;DR. Updated August 2026. Fastest path: install the Hatchable plugin. Run /plugins in the Codex CLI (or open Plugins in the Codex app), install Hatchable, approve the sign-in. Manual route: add [mcp_servers.hatchable] with url = "https://hatchable.com/mcp" to ~/.codex/config.toml, then run codex mcp login hatchable. Either way, OAuth signs you in and creates the free account. To add an HTTP MCP server that wants a bearer token instead, use the same url key plus bearer_token_env_var; that, per-project config and codex mcp list are covered below.

What is an MCP server in Codex?

OpenAI Codex is an AI coding agent with a desktop app, CLI, and IDE extension. It supports the Model Context Protocol (MCP), which lets it call external tools (databases, APIs, deployment targets) as first-class functions during a session. Registering an MCP server in Codex adds a new tool category to what Codex can do without any new model training. Codex also has a plugin directory: a plugin bundles an MCP server plus its setup, so installing one replaces the manual configuration entirely.

Hatchable's MCP server exposes tools for creating projects, deploying code, and querying the app's database, so Codex can take you from "describe the app" to "live URL" in one session.

The fast path: install the Hatchable plugin

Hatchable is a listed ChatGPT app, and OpenAI distributes listed apps to Codex as plugins. Installing the plugin does everything the manual steps below do:

1. Open the plugin directory

   In the Codex app, open the Plugins section. In the Codex CLI, run /plugins to open the plugin browser.

2. Install Hatchable

   Search for Hatchable, open it, and select Install.

3. Authenticate

   Approve the sign-in tab that opens on hatchable.com. If this is your first visit, approving also creates your free Hatchable account. No email step, no credit card.

4. Try it

   Start a new thread and ask Codex to do something that requires the server (or type @ and pick Hatchable to invoke it explicitly):

   "Build a small habit-tracker web app on Hatchable. Make it for personal use."

   Codex will propose a plan, ask for permission, then call Hatchable's tools to create the project, write the files, and deploy it. You'll get a live URL back in the same session.

The manual route: config.toml

Prefer to wire up the MCP server yourself, or on a locked-down setup where the plugin directory isn't available? Codex reads MCP servers from ~/.codex/config.toml (a project-scoped .codex/config.toml works too). The whole entry is two lines:

[mcp_servers.hatchable]
url = "https://hatchable.com/mcp"

Remote servers use the Streamable HTTP transport automatically when you give a url. No bearer token, header, or environment variable is needed. Then authenticate:

codex mcp login hatchable

A browser tab opens on hatchable.com. Approve, and Codex stores the OAuth credentials for future sessions. In the IDE extension, the same file is reachable from the gear menu via MCP settings → Open config.toml.

HTTP transport, bearer tokens, and per-project config

Hatchable is the easy case because it speaks OAuth. The same config.toml mechanism covers every other remote server you might want to add to Codex, so here is the general shape, checked against OpenAI's Codex documentation as of August 2026. Codex moves quickly; if a key below is rejected on your build, run codex --version and compare with the current docs.

Remote servers use url (Streamable HTTP)

Inside a [mcp_servers.<name>] block, a command key means a local STDIO server that Codex launches as a subprocess, and a url key means a remote server reached over Streamable HTTP. You never declare the transport by name; the key you use decides it. To add an HTTP MCP server to Codex, that is the whole entry:

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

If the server uses OAuth (as Hatchable does), follow it with codex mcp login example. Codex supports the current OAuth flavours for MCP, including dynamic client registration, so most hosted servers sign in with a browser tab and nothing else.

Bearer tokens: bearer_token_env_var

For a server that wants a static token, Codex deliberately does not let you paste the token into config.toml. You name an environment variable, and Codex reads it at connect time and sends it as Authorization: Bearer ...:

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

Then export the variable in the shell that launches Codex (export EXAMPLE_MCP_TOKEN=..., or put it in your shell profile). The _env_var suffix means "put the name here, not the value"; the most common mistake is pasting the token itself. Servers that want other headers have two more keys as of August 2026: http_headers for a map of static header values, and env_http_headers for headers whose values come from named environment variables. Recent Codex builds also accept the same thing from the CLI, roughly codex mcp add example --url https://mcp.example.com/mcp --bearer-token-env-var EXAMPLE_MCP_TOKEN; OpenAI's docs only show the STDIO form of codex mcp add, so check codex mcp add --help on your build before relying on those flags.

Per project vs. user-level

~/.codex/config.toml is your user-level config and applies to every Codex session. A .codex/config.toml inside a repository is project-scoped: Codex loads it only when you launch Codex from inside that directory tree, and only for projects you have marked as trusted (Codex normally asks about trust the first time you open a folder; an untrusted project's .codex/ layer is ignored). When both define the same key, the project file wins, and the closest .codex/config.toml to your working directory wins over ones further up. So "Codex MCP per project" is just a matter of which file the [mcp_servers.*] block lives in. Two cautions: the codex mcp add command writes to the user-level file, so project-scoped servers are added by editing .codex/config.toml by hand, and because that file tends to get committed, keep tokens in bearer_token_env_var rather than in the file.

Listing what is configured

• codex mcp list prints every configured server with its auth status (--json for machine-readable output).
• codex mcp get <name> shows one server's resolved config, which is handy when a project file and the user file disagree.
• Inside an interactive Codex session, /mcp shows the servers that are actually active in that session.
• codex mcp remove <name> deletes an entry, codex mcp login <name> starts OAuth, and codex mcp logout <name> clears stored credentials.

For the protocol itself, see what MCP is; to run your own server for Codex to call, see build an MCP server.

Removing or updating the server

Installed the plugin? Remove or disable it from the same Plugins section (or /plugins browser) you installed it from. Configured it manually? Delete the [mcp_servers.hatchable] block from config.toml. If OAuth ever falls out of sync (say you revoked Codex's access from your Hatchable account), run codex mcp login hatchable again (or re-authenticate the plugin) to re-link.

Troubleshooting

"Tool not available" or Codex doesn't list Hatchable tools

Walk through these in order:

• Is the plugin (or server) enabled? A disabled plugin, or a commented-out config block, surfaces no tools. Check the Plugins section or your config.toml.
• Did you authenticate? A server that's configured but not signed in won't expose any tools. Run codex mcp login hatchable, or re-run the plugin's sign-in.
• Restart the session. If you authenticated mid-session, start a fresh Codex thread so it re-queries the server's tool list.
• Check the URL. It's https://hatchable.com/mcp: no trailing slash, no /mcp/, and Streamable HTTP (not STDIO).

Sign-in does nothing, or the browser tab hangs

• Pop-up blocker. Some systems suppress the OAuth tab. Check your browser's site permissions for Codex, or the system default browser's pop-up settings.
• Corporate proxy or VPN. OAuth needs an outbound connection to hatchable.com from both Codex and your browser. If your browser works but Codex's background calls don't, look at your system proxy settings.
• TLS inspection. Some enterprise firewalls intercept HTTPS with a custom cert. Codex may reject those unless the cert is trusted at the OS level.

Codex runs in the cloud. Does OAuth still work?

Yes. Codex's cloud execution mode reuses the OAuth credentials stored when you authenticated locally. They ride along with the session, authenticate the MCP calls from the cloud runner, and aren't logged on OpenAI's side.