datatomcp
Sign inStart free

Codex MCP: add a remote MCP server to the Codex CLI

By Killian, founder · Updated 27 October 2026 · Markdown

To add a remote MCP server to OpenAI Codex, run codex mcp add <name> --url <url>, then codex mcp login <name> to sign in through your browser. The server is saved in ~/.codex/config.toml, which the Codex CLI, the Codex IDE extension and the ChatGPT desktop app all read, so you set it up once. This guide covers the command, the TOML for servers that use tokens, how to check the tools loaded, and the usual errors.

The example server is datatomcp, which lets Codex query your CSVs and Google Sheets.

1. Add the server

codex mcp add datatomcp --url https://app.datatomcp.com/mcp
codex mcp login datatomcp

The first command writes the server to your config. Recent versions (0.165 and later) also start the sign-in right away, printing the URL and opening your browser; if you close that, codex mcp login starts it again. For datatomcp you log in and approve read access to your datasets. Codex stores the token, so you only do this again if it expires or you log out. codex mcp list then shows the server with Auth OAuth.

If the server needs a pre-registered OAuth app, add --oauth-client-id <id> to codex mcp add. codex mcp login also accepts --scopes. Servers like datatomcp that support dynamic registration don’t need either.

2. Or edit config.toml

The command above produces an entry like this in ~/.codex/config.toml:

[mcp_servers.datatomcp]
url = "https://app.datatomcp.com/mcp"

A project can have its own .codex/config.toml, which Codex reads only in projects you’ve marked as trusted.

Servers that use a token instead of OAuth

Point Codex at an environment variable that holds the token. It’s sent as Authorization: Bearer <token>:

[mcp_servers.my-api]
url = "https://api.example.com/mcp"
bearer_token_env_var = "MY_API_TOKEN"
http_headers = { "X-Region" = "eu" }

http_headers sends fixed headers; env_http_headers maps header names to environment variables when the value is secret.

Useful options

[mcp_servers.datatomcp]
url = "https://app.datatomcp.com/mcp"
startup_timeout_sec = 20   # default 10
tool_timeout_sec = 60      # default 60
enabled_tools = ["list_datasets", "describe_dataset", "aggregate", "distinct_values", "query_rows"]

enabled_tools is an allow list and disabled_tools a deny list applied after it. Trimming tools keeps the model’s context smaller when a server exposes many.

3. Check the tools loaded

codex mcp list

lists the servers Codex has configured. Inside the codex TUI, /mcp shows connected servers and their tools. Then ask something only the server can answer:

Use datatomcp: list my datasets, then give me the total revenue per month for 2026 from the orders dataset.

Codex shows each tool call and asks for approval according to your approval settings.

Troubleshooting

  • The server is listed but has no tools. You haven’t signed in, or the token expired. Run codex mcp login datatomcp again.
  • Timeout at startup. Raise startup_timeout_sec. The default is 10 seconds.
  • 401 with a token server. The environment variable named in bearer_token_env_var isn’t set in the shell that started Codex. Variables set in another terminal don’t carry over.
  • Works in the CLI but not the IDE extension. Both read ~/.codex/config.toml. Restart the editor after changing it, and check that the editor was started from an environment where your variables are set.
  • Project config ignored. .codex/config.toml only loads in trusted projects.

A data server for Codex

Codex is good at code, and asking it to total a 100,000-row CSV by reading it is a poor use of context. With datatomcp connected, Codex sends a query and gets back the answer. The five tools are read-only: list_datasets, describe_dataset, query_rows (up to 1,000 rows per call), aggregate (counts, sums, averages, min, max, grouped) and distinct_values. Every result names the dataset version it came from, which helps when you check a migration or a report against the source.

Create a free account, add a CSV, a CSV link or a Google Sheet under Add data, and run the two commands above. If you’d rather call the data from code, the same datasets are available over REST: see Turn a CSV into a REST API.

FAQ

Where is the Codex MCP config? ~/.codex/config.toml, plus an optional .codex/config.toml per trusted project.

Does Codex support remote MCP servers over Streamable HTTP? Yes. Use url in the config or --url with codex mcp add.

Do I set it up separately in the IDE extension? No. The CLI, the IDE extension and the ChatGPT desktop app share the same MCP configuration.

Is this the same as adding a server to ChatGPT on the web? No. ChatGPT on the web uses its own custom MCP servers setup; see the ChatGPT guide.

More clients: Add a remote MCP server to any AI client · Claude Code · OpenCode