Codex and other clients

BrightSite works with any AI tool that supports MCP, the open standard for connecting assistants to outside services. This page has the configuration those tools expect, and covers Codex specifically.

For Claude, see Claude. For ChatGPT, see ChatGPT. Both have their own pages because both have a point-and-click route that avoids config files entirely.

What every client needs

The URL is the same for every customer. You do not put your own domain in it.

The generic configuration

Nearly every MCP client accepts this JSON shape. Paste it into whichever file your tool uses, replacing YOUR_API_KEY:

{
  "mcpServers": {
    "brightsite": {
      "url": "https://onbrightsite.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Some tools name the top-level key servers rather than mcpServers, and some want an explicit "type": "http" line alongside the URL. If your tool rejects the block above, check its own MCP documentation for the exact key names. The URL and header stay the same either way.

Get your key in BrightSite under User Settings, on the Security tab, in the API keys section. It is shown only once, when you create it, so copy it immediately. See API keys.

Signing in instead of pasting a key

If your tool supports it, you can connect by signing in through your browser rather than handling a key at all. BrightSite supports the standard OAuth sign-in flow that MCP clients use, including automatic client registration, so a tool that offers this handles the whole thing for you.

In practice: you add https://onbrightsite.com/api/mcp as a server with no key, the tool notices that authorization is required and opens a BrightSite page in your browser, you approve while signed in, and the tool is connected. You never see or store a key.

This is the better option wherever it is available. There is no secret sitting in a file, and you can withdraw access without disturbing your other tools. If your tool asks for a URL and nothing else, try it. If it needs a key it will say so, and you can fall back to the header method above.

Codex

Codex, OpenAI's coding agent, reads MCP servers from config.toml in your ~/.codex folder (a project can also carry its own .codex/config.toml). A server entry with a url is treated as a remote HTTP server, and the key is read from an environment variable rather than written into the file:

[mcp_servers.brightsite]
url = "https://onbrightsite.com/api/mcp"
bearer_token_env_var = "BRIGHTSITE_API_KEY"

Set BRIGHTSITE_API_KEY in your shell to the key from BrightSite. The same setup from the command line is codex mcp add brightsite --url https://onbrightsite.com/api/mcp --bearer-token-env-var BRIGHTSITE_API_KEY.

To sign in instead of using a key, leave out the bearer_token_env_var line and run codex mcp login brightsite, which opens the BrightSite approval page in your browser.

Restart Codex after saving. New MCP connections are read at startup.

Claude Code and other CLI agents

Claude Code is covered on the Claude page. Other command-line agents take the same URL; use their own MCP settings with the generic block above, and prefer browser sign-in where the tool offers it.

Before your first real request

Ask your tool to list your accounts first. Every action needs an account id and your assistant cannot guess it:

List my BrightSite accounts.

Then check the connection with something that only reads:

List my BrightSite accounts, then show me the pages on the first one.

Real account names and real page titles means you are connected.

If it does not connect

• No BrightSite tools listed. Restart the tool completely, because MCP configuration is read at startup. Then check your JSON is valid: one missing comma makes the whole file be ignored without a warning.
• Authentication rejected. The header must be the word Bearer, a single space, then the key. Keys start with bs_mcp_. If you are not certain the key was copied whole, revoke it and make a new one.

Missing accounts, billing refusals, permission errors and rate limits are the same for every tool, and are covered on Connecting an AI tool.

One thing to watch

Unlike Lumi, an outside tool does not necessarily ask before making a change. Whatever confirmation your client offers is the only checkpoint you get, so find out what it does before pointing it at a live client site. See Working safely with AI.

Related

• Connecting an AI tool
• API keys
• What AI tools can do
• Working safely with AI