Skip to content
← All articles

How to Add an MCP Server to Codex

Codex's docs list no flag for bearer tokens, so config.toml names the env var that holds the key. Add an MCP server to Codex with codex mcp add.

John Guerrero, with a beard and round glassesBy John GuerreroUpdated November 9, 2026
Abstract illustration: a configuration table between brackets with the new server's section highlighted

Frequently asked questions

How do I add an MCP server to Codex?

Run codex mcp add with a name and either --url for a remote server or a command after -- for a local one. Codex writes the entry to ~/.codex/config.toml, where you can add settings such as a bearer token read from an environment variable.

Where is the Codex MCP configuration stored?

In ~/.codex/config.toml by default, with one [mcp_servers.<name>] table per server. Codex also reads a project-scoped .codex/config.toml, which only works in trusted projects.

How do I send an API key to a remote MCP server from Codex?

Set bearer_token_env_var in the server's table to the name of an environment variable that holds the key. Codex sends it in the Authorization header. For other headers there are http_headers for fixed values and env_http_headers for values read from the environment.

How do I know the server is working?

Run codex mcp list to see the configured servers, and type /mcp inside the Codex interface to see the active ones. If the actions don't show up, test the URL and key with curl outside Codex.

Should I put the API key directly in config.toml?

No. Put the key in an environment variable and reference only the variable's name in the file. That way the config can be shared or backed up without exposing a secret.

Which Clautia actions can Codex use?

All ten. Four only read (brands_list, accounts_list, posts_list and posts_get), four write (posts_create, posts_schedule, ai_draft and ai_adapt, where ai_draft and ai_adapt return text without saving it) and two are delicate and need a confirmation token (posts_publish and posts_cancel). We tested codex-cli 0.166 on 7 November 2026 against the staging MCP server with a read-only key, and Codex saw all ten.