Browserless MCP in Codex
The Codex CLI and app connect to the hosted Browserless MCP server with OAuth by default, or with an API token read from an environment variable. Once it's connected, Codex can scrape, search, crawl, and drive a cloud browser with the Browserless MCP tools.
- A Browserless API token from your account dashboard, or a Browserless account for OAuth sign-in
- Codex CLI or app installed
Connect to the hosted server
The hosted server runs at https://mcp.browserless.io/mcp, so there's nothing to install.
The hosted server supports OAuth. Add it, then sign in:
codex mcp add browserless --url https://mcp.browserless.io/mcp
codex mcp login browserless
To use an API token instead, add to ~/.codex/config.toml:
[mcp_servers.browserless]
url = "https://mcp.browserless.io/mcp"
bearer_token_env_var = "BROWSERLESS_TOKEN"
Set BROWSERLESS_TOKEN in your environment before starting Codex. In the ChatGPT desktop app, go to Settings → MCP servers → Add server, choose Streamable HTTP, save, then select Restart (and Authenticate to sign in with OAuth).
To use a region other than US West, add an x-browserless-api-url header, or a browserlessUrl query parameter on the server URL for clients that only take a URL. See regional endpoints.
Run the server locally
To run the MCP server process on your machine instead, use the @browserless.io/mcp npm package over stdio. You need Node.js 24 or newer. Browser work still runs on Browserless, so this is mainly for pinning a server version (add it to the package name, for example @browserless.io/mcp@1.41.0) or pointing at a self-hosted instance with BROWSERLESS_API_URL. Both setups use the server name browserless, so replace the hosted entry with this one rather than adding both.
Run in your terminal:
codex mcp add browserless --env BROWSERLESS_TOKEN=YOUR_API_TOKEN_HERE \
-- npx -y @browserless.io/mcp
Or add to ~/.codex/config.toml:
[mcp_servers.browserless]
command = "npx"
args = ["-y", "@browserless.io/mcp"]
[mcp_servers.browserless.env]
BROWSERLESS_TOKEN = "YOUR_API_TOKEN_HERE"
Check the connection
Run codex mcp list and check browserless appears. Inside a Codex session, /mcp lists the connected servers and their tools.
FAQ & Troubleshooting
Codex connects but the token isn't sent
bearer_token_env_var takes the name of an environment variable, not the token itself. Set bearer_token_env_var = "BROWSERLESS_TOKEN" and export BROWSERLESS_TOKEN in the shell that starts Codex.
The server connects but every tool call returns 401 Unauthorized
The token is missing or wrong. Copy it again from your account dashboard and check the header reads Bearer followed by the token, with no quotes or trailing whitespace inside the value. If you used an environment variable, confirm it's set in the environment the client was launched from. GUI apps started from the dock or Start menu don't see variables exported in your shell profile.
The connection fails with an SSE error like Non-200 status code (400)
The hosted server speaks Streamable HTTP only and doesn't support the legacy SSE transport. Check the client entry is using its HTTP transport (see the config above), not an SSE one.