MCP Integration

What this does

MCP (Model Context Protocol) is a standard way for AI tools to connect to approved business context and capabilities. BrainRoad’s public MCP endpoint lets an outside AI, like Claude Code or Codex on your laptop, work from the same Business Brain your hosted helper uses:

• Search your Brain, read wiki pages, look up customers, ask questions grounded in your documents
• Add notes back into the Brain
• Propose work into your Inbox and check what happened to it

The one thing it can never do: approve. Anything an external tool proposes lands as a pending draft in your Inbox for you to review. There is no approve tool over MCP, by design.

Setup

1. Create a connector key

Go to Dashboard → API (“Developer Access”) and create a key with the “Brain + Inbox connector (recommended)” preset. This makes a scoped key bound to your helper, so the external AI acts as a named identity and never needs internal IDs. Copy the key when it appears; it is shown once.

The endpoint is always:

https://app.brainroad.com/mcp/brain

The dashboard shows ready-made setup snippets for Claude Code and Codex right after key creation, plus a one-click connection test.

2. Connect Claude Code

claude mcp add --transport http brainroad https://app.brainroad.com/mcp/brain \
  --header 'Authorization: Bearer ${BRAINROAD_API_KEY}'
read -rsp 'BrainRoad API key: ' BRAINROAD_API_KEY; echo
BRAINROAD_API_KEY="$BRAINROAD_API_KEY" claude

The environment-variable pattern keeps the key out of your shell history and saved config.

3. Connect Codex

codex mcp add brainroad --url https://app.brainroad.com/mcp/brain \
  --bearer-token-env-var BRAINROAD_API_KEY
read -rsp 'BrainRoad API key: ' BRAINROAD_API_KEY; echo
BRAINROAD_API_KEY="$BRAINROAD_API_KEY" codex

Any MCP client that supports HTTP transport with a bearer header works the same way. Hosted Claude.ai custom connectors require OAuth and cannot use this static key today.

4. Try it

Ask your connected tool something like: “Search my Business Brain for the Hendersons’ last quote.” Or: “Draft a follow-up reply for the Miller thread and propose it for my review.”

Available tools

Your key’s scopes decide which tools the client sees, and the visible list is exactly what the key can call.

Business Brain tools (scopes brain:read, brain:write, brain:ask): search, lookup_entity, list_collections, list_wiki_pages, get_wiki_page, list_documents, get_relationships, recent_qa, ingest_note, ask, query_graph, list_compiled_views, list_beacons, acknowledge_beacon, complete_beacon, snooze_beacon.

Review-queue tools (scopes triage:propose, triage:read):

Tool	Scope	What it does
triage_propose	triage:propose	Stages a pending card in your Inbox (for example an email reply draft, a Brain note, or a connector call). Never auto-approves or executes
triage_list	triage:read	Lists pending cards (default 20, max 50)
triage_status	triage:read	Checks the outcome of one card
get_work_record	triage:read	Reads a bounded slice of your Work Ledger

Rules the endpoint enforces

• Scoped keys only. A legacy full-access key with no scopes is rejected with 403 and a link to mint a proper connector key. Scopes are never widened silently.
• Trial wall at authentication. If your 30-day trial has ended, the endpoint returns 402 with an upgrade link before any tool runs. See Plans & Pricing.
• Rate limit: 120 requests per minute per key.
• Transport: HTTP JSON-RPC. Request bodies up to 5 MB.

The per-agent MCP endpoint (advanced)

Separate from the Brain endpoint above, a running OpenClaw helper also exposes its own runtime MCP endpoint at https://app.brainroad.com/gw/YOUR_USER_ID/mcp, authenticated with your Gateway Token (not a brk_ key). This speaks to the helper runtime itself: the same operator methods as WebSocket RPC. Find the exact URL, token, and config snippets on Dashboard → API while your helper is running. The Gateway Token has full access to your helper, so treat it like a password.

Troubleshooting

• 403 insufficient_scope: your key has no scopes (legacy mode) or is missing the scope a tool needs. Create a new connector-preset key.
• 402: trial ended; upgrade to continue using developer access.
• Tool missing from the list: the key was created without that scope. The tool list always matches what the key can actually call.
• Client does not pick up the server: most MCP clients read config at startup; restart the client after adding the server.