How to add an MCP server to Codex

TL;DR. Open Codex → Settings → MCP servers → Add server, name it, paste the URL, save, then click Authenticate. For Hatchable, the URL is https://hatchable.com/mcp — 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 and CLI. 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.

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.

Before you start

• Codex installed. Grab the desktop app from openai.com/codex and sign in with your OpenAI account. The GUI below ships in recent builds — if you don't see an MCP servers tab, update to the latest version.
• That's it. Hatchable's MCP server speaks OAuth, so there's no token to copy or environment variable to export. Codex's first call pops a browser tab that signs you in and creates your free Hatchable account in the same step.

Add the server

1. Open Codex settings

   In the Codex desktop app, open Settings from the sidebar (or the gear icon), then select MCP servers. Click + Add server.

2. Fill in the custom MCP form

   In the Connect to a custom MCP dialog:

   • Name: Hatchable
   • Transport: select Streamable HTTP
   • URL: https://hatchable.com/mcp

   Leave Bearer token env var, Headers, and Headers from environment variables blank — Hatchable uses OAuth, so none of them apply. Click Save.

3. Authenticate

   Codex returns you to the MCP servers list with hatchable now showing. Click the Authenticate button on that row. A browser tab opens on hatchable.com — approve, and Codex stores the OAuth credentials for future sessions.

   If this is your first visit to Hatchable, approving also creates your free account. No email step, no credit card.

4. Try it

   Back in Codex, ask it to do something that requires the server:

   "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.

Removing or updating a server

Click the gear icon next to hatchable in the MCP servers list. From there you can disable the server (toggle off), edit the URL, or remove it entirely. If OAuth ever falls out of sync — say you revoked Hatchable access from your account — click Authenticate again to re-link.

Troubleshooting

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

Walk through these in order:

• Confirm the toggle is on. The switch on the right of the server row controls whether Codex surfaces the server's tools. Grey means off.
• Did you authenticate? A server that's saved but not authenticated won't expose any tools. The row shows an Authenticate button when that's the case.
• Restart the session. If you authenticated mid-session, start a fresh Codex conversation 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).

Authenticate button 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.