How to add an MCP server to Codex

TL;DR. 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.

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.

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.