Codex MCP setup: config.toml and a browser server

Add an MCP server to OpenAI Codex: the config.toml entry, codex mcp add, how to check it loaded, and the errors Codex prints when it does not.

Last updated Sep 22, 2026

Codex keeps its MCP servers in TOML rather than JSON, one table per server. Which transport it uses follows from which keys are present: a url means HTTP, a command means stdio.

The worked example is Scalebrowser's own server, which gives the agent a real browser on your machine. Any other HTTP MCP server takes the same entry with its own address.

Before you start

Everything below assumes a daemon that is already running and a token to reach it with.

Windows desktop app

The app starts the daemon for you. The token is the contents of %LOCALAPPDATA%\Scalebrowser\token, and the address it is listening on is the native_addr field of %LOCALAPPDATA%\Scalebrowser\runtime.json. That is usually 127.0.0.1:8787, but the app moves up a port when something else already holds it.

Self-hosted daemon

scalebrowser-daemon --generate-token prints a token and stores it under <data_dir>/token. The address is whatever bind_addr says, which is 127.0.0.1:8787 unless you changed it. See Install & run.

The token is a full-power credential. It reaches every profile, every stored session and the whole management API. Treat it like a password: keep it out of a repository, and prefer your client's environment-variable syntax over a literal in a config file that gets committed.

Add the server

~/.codex/config.toml applies everywhere. A .codex/config.toml inside a project applies there, but only once you have marked the project as trusted, and it wins over the global file. The Codex CLI, the IDE extension and the ChatGPT desktop app all read the same file.

~/.codex/config.tomltoml

[mcp_servers.scalebrowser]
url = "http://127.0.0.1:8787/v1/mcp"
bearer_token_env_var = "SCALEBROWSER_TOKEN"
startup_timeout_sec = 20
tool_timeout_sec = 120

bearer_token_env_var names an environment variable rather than carrying the token, and Codex sends its value as Authorization: Bearer …. Export it before you start Codex. A literal bearer_token = "…" in the file is refused, so there is no way to commit the token by accident.

The CLI writes the same entry for you, always into the global file:

bash

codex mcp add scalebrowser --url http://127.0.0.1:8787/v1/mcp \
  --bearer-token-env-var SCALEBROWSER_TOKEN

It leaves the two timeouts at their defaults, 10 seconds to start and 60 seconds per tool call. Add them to the file afterwards.

A tool call can take longer than a default timeout allows. wait_for waits for a page to settle and press_and_hold holds a key for about ten seconds, so a per-tool ceiling below roughly 120 seconds will cut off calls that were going to succeed.

Check that it loaded

CLI: codex mcp list shows every configured server, and codex mcp get scalebrowser shows one. Inside a session, /mcp lists the tools each server exposes, /mcp verbose with detail.
IDE extension: the gear menu, then MCP servers. After editing the file by hand, restart the extension.
ChatGPT desktop app: Settings, then MCP servers, then restart the app.

Codex speaks stdio and Streamable HTTP, and a plain http:// address on loopback is fine.

When it does not load

Codex says	What to do
`Environment variable SCALEBROWSER_TOKEN for MCP server 'scalebrowser' is not set`	The process that started Codex never saw the variable. An IDE or the desktop app does not read your shell profile; set it where that process starts, or start it from a shell that has it.
MCP client for `scalebrowser` timed out after 10 seconds	The daemon did not answer in time. Check it is running and that the port in `url` matches `native_addr` in `runtime.json`, then raise `startup_timeout_sec`.
MCP client for `scalebrowser` failed to start	Usually a wrong address or a stopped daemon. `curl http://127.0.0.1:8787/health` answers without a token and tells you which.
`bearer_token is not supported`	The file carries the token itself. Replace the line with `bearer_token_env_var`.

A 401 in the details means the token reached the daemon and was refused: copy it again from the app.

What the agent can do now

Ask it to open a page and it will lease a profile, bind a tab and start reading. The tool set, the page map and the failure shapes are on MCP server; what the agent is allowed to do is decided by the daemon, not by the client, so see tool profiles.

Run it on your own machine

Seven days to try it with your own agents on your own sites. Starting the trial needs a card.

Get started