Connect an AI assistant

Connect an AI assistant to brix and ask it about your business in plain English: “How did HVAC sell this month?”, “Which quote requests for Atlas Finance are still open?”, “What’s on this job?”. By default the assistant only reads your brix data and answers. You can also let it change your price book, and brix asks you separately for that.

What you need

An API key that acts as you. Create it on the API Keys page, set Acts as to yourself, and give it the *:read scope. The assistant then sees exactly what you see in brix and nothing more.
The brix connector address:

https://mcp.brixco.io/mcp

The key saved on your computer as BRIX_API_KEY. Every setup below reads the key from there, so it never sits in a chat message or a shared settings file.

Open Terminal.

Run this. It asks for the key without showing it, so the key never appears on screen or in your command history:

read -s "k?Paste your brix key, then press Return: " && echo "export BRIX_API_KEY=\"$k\"" >> ~/.zshrc && unset k

On Linux with bash, use this instead:

read -s -p "Paste your brix key, then press Return: " k && echo "export BRIX_API_KEY=\"$k\"" >> ~/.bashrc && unset k

Close Terminal and open it again. Start your assistant from a new window so it can see the key.

Open the Start menu and search for Edit environment variables for your account.
Under User variables, click New.
Enter BRIX_API_KEY as the name and paste your key as the value. Click OK, then OK again.
Restart your assistant so it can see the key.

Connect your assistant

Pick your assistant. For Claude Code, Codex, OpenClaw and Hermes you copy one message and send it to the assistant: it sets itself up and checks the connection. The manual steps underneath do the same thing by hand.

Works in the Claude Code terminal app and in its VS Code and JetBrains extensions, which share the same settings.

Copy and send this to Claude Code:

Set up the brix connector for me. Run exactly:
claude mcp add --transport http --scope user brix https://mcp.brixco.io/mcp --header 'Authorization: Bearer ${BRIX_API_KEY}'
Keep the single quotes so the key is read from my BRIX_API_KEY setting when you connect, and never print, save or ask me for the key itself.
Then run `claude mcp list` and tell me whether brix shows Connected.

Or by hand: run the same claude mcp add command in your terminal, then claude mcp list. You should see brix: https://mcp.brixco.io/mcp (HTTP) - ✔ Connected. Inside Claude Code, type /mcp to see the brix tools.

Works in the Codex terminal app, the Codex IDE extension and the ChatGPT desktop app, which share the same settings.

Copy and send this to Codex:

Set up the brix connector for me. Run exactly:
codex mcp add brix --url https://mcp.brixco.io/mcp --bearer-token-env-var BRIX_API_KEY
The key is read from my BRIX_API_KEY setting; never print, save or ask me for the key itself.
Then run `codex mcp list` and confirm brix is enabled with a bearer token, and tell me to start a new Codex session.

Or by hand: run the same codex mcp add command. It adds this to ~/.codex/config.toml:

[mcp_servers.brix]
url = "https://mcp.brixco.io/mcp"
bearer_token_env_var = "BRIX_API_KEY"

Start a new Codex session and type /mcp to see the brix tools.

Open ~/.cursor/mcp.json (create it if it doesn’t exist). To share the setup with one project only, use .cursor/mcp.json in that project instead.

Add brix:

{
  "mcpServers": {
    "brix": {
      "url": "https://mcp.brixco.io/mcp",
      "headers": { "Authorization": "Bearer ${env:BRIX_API_KEY}" }
    }
  }
}

Restart Cursor from a window that can see BRIX_API_KEY.
Check that brix is switched on in Cursor’s MCP settings and its tools are listed.

Copy and send this to OpenClaw:

Set up the brix connector for me. Add this server to ~/.openclaw/openclaw.json under mcp.servers, keeping everything else unchanged:
"brix": {
  "url": "https://mcp.brixco.io/mcp",
  "transport": "streamable-http",
  "headers": { "Authorization": "Bearer ${BRIX_API_KEY}" }
}
Keep ${BRIX_API_KEY} exactly as written so the key is read from my BRIX_API_KEY setting; never print, save or ask me for the key itself.
Then run `openclaw mcp doctor brix --probe` and tell me whether it connected and which brix tools it found.

Or by hand: add the same brix block under mcp.servers in ~/.openclaw/openclaw.json, then run openclaw mcp doctor brix --probe. The transport line matters: without it OpenClaw tries an older connection type that brix doesn’t use. The Gateway picks up the change by itself; brix tools appear as brix__whoami, brix__list_clients and so on.

Copy and send this to Hermes:

Set up the brix connector for me. Add this to ~/.hermes/config.yaml under mcp_servers, keeping everything else unchanged:
  brix:
    url: "https://mcp.brixco.io/mcp"
    headers:
      Authorization: "Bearer ${BRIX_API_KEY}"
Keep ${BRIX_API_KEY} exactly as written so the key is read from my BRIX_API_KEY setting; never print, save or ask me for the key itself.
Then run `hermes mcp test brix`, reload with /reload-mcp, and tell me which brix tools you can see.

Or by hand: add the same block under mcp_servers in ~/.hermes/config.yaml, run hermes mcp test brix, then type /reload-mcp in your Hermes session. brix tools appear as mcp_brix_whoami, mcp_brix_list_clients and so on.

Claude on the web and the Claude desktop app connect through custom connectors. One-click sign-in for brix is on its way. Until then, a custom connector can only send your key if your Claude organisation has Request headers turned on (a limited beta from Anthropic).

In Claude, open Customize → Connectors → Add custom connector.
Name it brix and paste https://mcp.brixco.io/mcp.
Set Authentication to No sign-in.
Under Request headers, add authorization with the value Bearer followed by your key. Type the word Bearer and a space yourself.
Save, then switch brix on for a chat with + → Connectors.

If you don’t see Request headers, use Claude Code for now, or wait for one-click sign-in.

Any assistant that supports remote MCP servers with a custom header can connect. Give it:

Setting	Value
Address	`https://mcp.brixco.io/mcp`
Connection type	Streamable HTTP (sometimes shown as “HTTP”; not SSE)
Header	`Authorization: Bearer` followed by your key, read from `BRIX_API_KEY`

If the assistant can only start a local program, it can’t connect to brix directly yet.

Try it

Once connected, start with these:

Which brix workspace are you connected to, and what can you see?

How did each business unit sell this month compared with last month?

Show me the open quote requests for <client name> and what's quoted on each.

The assistant picks the right brix tool for each question. It can look up dashboards, the revenue scorecard, goals, reviews, clients, quote requests and quote options, jobs, agreements, client assets, materials, services and business units.

What the assistant can and can’t do

It reads by default. Unless you also allow it to change your price book, it can’t create, change or delete anything in brix.
It sees what you see. With a key that acts as you, anything you can’t open in brix, the assistant can’t read either.
It sees one workspace: the one the key belongs to.
It works in pages. Long lists come back a page at a time. Ask for the next page, or narrow the question (“open quote requests from last week”) for faster answers.
It treats brix data as data. A client note or quote description that reads like an instruction is still just text from your records.

Let the assistant change your price book

When you connect an assistant by signing in, brix shows a consent screen. Reading your data is always part of it. A second, optional permission, Change your price book, is asked separately, so you can leave it off.

If you allow it, the assistant can add and edit services, materials, material packs, pick lists, tech levels, equipment, assets, labour, markups, discounts and categories.

Open quotes reprice. Quotes that are still open update to the new prices straight away.
Changes overwrite. A change replaces the existing value, including values that came from a catalogue import or a service link.
Nothing is permanently deleted. The assistant can remove items from use, but brix keeps them and never erases them.

The Access column on the Connected apps list on the API Keys page shows which assistants can read only and which can also change the price book. To take the permission away, remove the connection there and connect again without it.

What leaves brix

Whatever the assistant looks up is sent to the company that runs it (for example Anthropic for Claude, OpenAI for Codex), so it can answer you. That can include client names, contact details, addresses, quote amounts and notes. Their own terms cover how they handle it. If that isn’t acceptable for some of your data, use a key that acts as a user who can’t see it.

Things to check

The assistant says the connection failed or shows an authorisation error

Check that BRIX_API_KEY is set in the window you started the assistant from: close it, open a new terminal or restart the app, and try again. Claude Code shows Missing environment variables: BRIX_API_KEY when it can’t see the key. If the key is set, open the API Keys page and check the key is still Active.

The assistant says the connector is not enabled for your account

The AI assistant connector is switched on per workspace. Ask brix support to switch it on for yours.

The assistant can’t see dashboards, goals or the scorecard

The assistant follows your own permissions. If you can’t open the Company Dashboard or Revenue Scorecard in brix, the assistant can’t read them either. Ask your workspace owner if you need access. Also check the key has the *:read scope.

The assistant says brix is busy

Each workspace can run up to four lookups at once. Extra lookups wait up to five seconds for a free slot, then come back as busy. Wait a few seconds and ask again, or ask for fewer things in one go.

OpenClaw connects but finds no tools

Check the brix block includes "transport": "streamable-http". Without it OpenClaw uses an older connection type that brix doesn’t accept.

What happens next

To stop an assistant using brix, revoke its key on the API Keys page. It loses access straight away.
To give a script or integration access instead of an assistant, see Giving a key to an AI agent.