Codex MCP config.toml: a remote fetch server with a bearer key

Codex CLI keeps its MCP servers in TOML, not JSON, and it has its own key for a bearer token. A snippet copied from a Claude Code or Cursor guide will not work here. This post sets up a remote fetch server in Codex from the command line and in config.toml, and shows the commands that prove it connected.

Checked against the Codex MCP docs and the codex mcp source on 2026-11-13.

Add the server from the command line

codex mcp add with --url registers a Streamable HTTP server. Export the key first, then name the variable that holds it:

export FETCHMCP_API_KEY=YOUR_KEY

codex mcp add fetchmcp --url https://fetchmcp.net/mcp \
  --bearer-token-env-var FETCHMCP_API_KEY

--bearer-token-env-var takes a variable name, not a token. In the Codex source the flag requires --url and is documented as valid only for Streamable HTTP servers. Without --url, codex mcp add expects a command to launch a stdio server instead.

The command writes a global entry and prints Added global MCP server 'fetchmcp'. If Codex detects OAuth support on the server, it starts a login right away. If it cannot tell, it suggests codex mcp login fetchmcp. A server that uses a static bearer key needs neither.

The same entry in config.toml

~/.codex/config.toml holds one table per server. This is the entry the command above produces, written by hand:

[mcp_servers.fetchmcp]
url = "https://fetchmcp.net/mcp"
bearer_token_env_var = "FETCHMCP_API_KEY"

bearer_token_env_var names the variable whose value Codex sends as a bearer token in the Authorization header. The file holds only the name, so it is safe to keep in a dotfiles repo.

http_headers is the other way to send a header. It maps header names to static values, which means the key would sit in the file as plain text. Use it for headers that are not secret.

env_http_headers maps header names to environment variable names. Use it when a server wants its key in a header other than Authorization.

Optional keys worth knowing

1. enabled = false turns the server off without deleting the table.
2. required = true makes Codex fail at startup if this server is not ready. Useful when a task depends on fetching pages.
3. enabled_tools is an allow list of tool names. disabled_tools is a deny list, applied after it.
4. startup_timeout_sec (default 10) and tool_timeout_sec (default 60) are the server's start and tool-call limits, in seconds. The timeout post compares them with other clients.

For a fetch server, an allow list keeps the tool set explicit:

[mcp_servers.fetchmcp]
url = "https://fetchmcp.net/mcp"
bearer_token_env_var = "FETCHMCP_API_KEY"
enabled_tools = ["get_page_contents", "get_account_status"]

Project config needs a trusted project

.codex/config.toml in a repository can define servers for that project only. The Codex docs mark this as "trusted projects only": until you trust the project, its servers do not load. If a teammate reports that the shared server is missing, check trust before you check the URL.

The same rule as everywhere else applies to the committed file: keep bearer_token_env_var and let each developer set the variable in their own environment.

The configuration is shared. Codex CLI, the Codex IDE extension and the ChatGPT desktop app all read it, so one entry covers all three.

Check what Codex stored and whether it connected

codex mcp get fetchmcp prints the stored entry: transport: streamable_http, the url, and bearer_token_env_var with the variable name. Any http_headers values are masked as *****, so the output is safe to paste into a ticket.

codex mcp list prints HTTP servers in their own table with the columns Name, Url, Bearer Token Env Var, Status and Auth. Add --json for a machine-readable version.

/mcp inside the Codex TUI lists the servers that are active in the current session. If fetchmcp is missing there but present in codex mcp list, look at enabled and, for project servers, at trust.

When the key does not arrive

bearer_token_env_var reads the variable from the environment Codex runs in. Export it in your shell profile, not only in one terminal tab, and start Codex from a shell that has it.

The Codex docs add a detail that matters here: if no credential source resolves, Codex can connect to the server without authentication. With a server that requires a key, expect an authentication error rather than a missing-variable warning. The auth setting (default oauth) is tried only after configured bearer tokens and authorization headers.

For the other clients' versions of this setup, see the remote MCP server setup guide.

Try it with a real server

FetchMCP API runs a stateless Streamable HTTP server that takes Authorization: Bearer <key>, the same key as its REST API, so the config.toml entry above is all Codex needs. The MCP server registers 2 tools. get_page_contents reads one public URL per call, and get_account_status shows credits left, plan and rate limit without spending credits. Failed fetches cost 0 credits.

Copy the current URL from the MCP docs and request a key.