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

> Add a remote MCP server to OpenAI Codex with codex mcp add and codex mcp login, or config.toml: tokens, timeouts, tool filters and fixes.

Source: https://datatomcp.com/guides/codex-mcp · By Killian · Updated 2026-10-27

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

```bash
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`:

```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>`:

```toml
[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

```toml
[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

```bash
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](https://app.datatomcp.com/login), 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](/guides/csv-to-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](/guides/chatgpt-custom-connector-spreadsheet).

More clients: [Add a remote MCP server to any AI client](/guides/add-remote-mcp-server) · [Claude Code](/guides/claude-code-mcp) · [OpenCode](/guides/opencode-mcp)