How to add an MCP server to Codex

TL;DR. Add the MCP server to ~/.codex/config.toml as a [mcp_servers.*] block, and set the bearer token as an environment variable so Codex picks it up at launch. For Hatchable: one config block plus export HATCHABLE_API_KEY="..." in your shell.

What is an MCP server in Codex?

OpenAI Codex is a terminal-based AI coding agent — a command-line cousin of Claude Code. 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. If you don't have it: npm install -g @openai/codex, then run codex login to connect your OpenAI account.
• A bearer token for the MCP server you're adding. For Hatchable, click Copy on the Codex snippet at hatchable.com — you'll get a token and config ready to paste.
• Your ~/.codex/ directory exists. Codex creates it on first run; if you haven't run Codex yet, run codex once and quit out, or just mkdir -p ~/.codex.

Add the server

1. Export the bearer token as an env var

   Codex's config references env vars by name rather than storing secrets in the TOML file. Put this in your shell profile (~/.zshrc, ~/.bashrc, or equivalent):

   export HATCHABLE_API_KEY="YOUR_TOKEN"

   Reload your shell (source ~/.zshrc) before continuing so the variable is available to Codex when it launches.

2. Add the server block to ~/.codex/config.toml

   Open ~/.codex/config.toml in your editor and append:

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

   The key hatchable after the dot is the local name Codex uses to refer to the server — you can set it to anything, but keep it short and lowercase. For additional MCP servers, repeat the block with a different name.

3. Restart Codex and verify

   Fully quit any running Codex sessions and restart:

   codex

   In the session, ask Codex to list its tools: "What tools do you have available?" You should see Hatchable's tools (like create_project, deploy, query_database) in the response. If they're missing, jump to Troubleshooting below.

4. Try it

   Ask Codex 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

Remove: delete the [mcp_servers.hatchable] block from config.toml. Codex picks up the change on next launch.

Rotate the token: generate a new one, replace HATCHABLE_API_KEY in your shell profile, restart your shell. The config file doesn't need to change.

Troubleshooting

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

Walk through these in order:

• Confirm the env var is set in the shell that launched Codex. Run echo $HATCHABLE_API_KEY — if it's empty, the variable didn't export into this shell. Sourcing ~/.zshrc requires a restart in some terminals (iTerm, VS Code integrated terminal).
• Check the TOML syntax. TOML is unforgiving; a missing quote or wrong bracket will silently break the entire section. Paste your config.toml into toml-lint.com if you suspect a typo.
• Check you restarted Codex. Codex loads MCP servers at launch — edits to config.toml don't take effect mid-session.
• Token expired? Hatchable auto-signup tokens are valid for 30 days. If yours is older, get a new one at hatchable.com.

Codex says "failed to connect to MCP server"

Almost always a network or URL problem:

• Check the URL. It's https://hatchable.com/mcp — no trailing slash, no /mcp/.
• Corporate proxy or VPN? Codex uses Node's HTTP stack, which honors HTTPS_PROXY / HTTP_PROXY env vars. Set those in the same shell before launching Codex if your network requires them.
• TLS inspection? Some enterprise firewalls intercept HTTPS with a custom cert. Node may reject those unless you add the cert to NODE_EXTRA_CA_CERTS.

Codex runs in the cloud — does it still see my env vars?

Yes. Codex's cloud execution mode uses a sandboxed runner that inherits the env vars you exported locally for the purpose of this session. The bearer token isn't logged on OpenAI's side; it's used only to authenticate the MCP calls.