How Hives Work
When an expert needs to use a tool (e.g. read a Google Sheet), it connects to the appropriate hive’s MCP server. The hive authenticates with the external service using the credentials you configured, executes the tool call, and returns the result to the expert. Key points:- Each hive is an MCP server. Hives follow the same Model Context Protocol standard as custom MCP servers, but they’re pre-built and maintained by Braintrust.
- Tools are discovered at runtime. When the expert connects to a hive, it receives the list of available tools from that hive.
- Hives are modular. Each hive covers one service. Add only the hives your expert actually needs.
Per-User Credential Isolation
Every user who hires an expert configures their own credentials for each hive independently. This means:- Your Google account connected to the Google Sheets hive is yours alone — no other user of the same expert shares it.
- Revoking your credentials does not affect other users.
- Expert builders never see or have access to your credentials.
Adding Hives to an Expert
When creating or editing an expert:- Navigate to the Config step.
- Click Add Hive to open the hive catalog.
- Select the hive you need (e.g. Google Sheets).
- Save the expert.
Hive Env Overrides
Some hives accept environment variable overrides — default values set at the expert level that apply to all users of that expert. Example: A Jira hive might accept aJIRA_PROJECT override so the expert always defaults to a specific project.
Guidelines for Hive Env Overrides:
- Do use them for safe, shared defaults (default project, default database name, base URL).
- Do not use them for secrets, API keys, or credentials — those belong in the per-user credential flow.
- Overrides are visible to anyone who can edit the expert.
Popular Hives
| Hive | What It Enables | Auth Type |
|---|---|---|
| Google Drive | Search files, read documents, organize content | OAuth |
| Google Docs | Create, read, and update documents | OAuth |
| Google Sheets | Read, analyze, and write spreadsheet data | OAuth |
| Gmail | Draft, search, and organize emails | OAuth |
| Google Calendar | Read schedule, create and update events | OAuth |
| Notion | Read and update pages and databases | OAuth / API key |
| Supabase | Execute SQL queries and manage data | API key |
| Jira (Atlassian) | Search, create, and update issues | OAuth |
| NetSuite | Run reports and custom SuiteQL queries | OAuth / token |
| QuickBooks | Search transactions, bills, vendors, invoices | OAuth |
| GitHub | Search repos, issues, PRs, code | OAuth / token |
Troubleshooting
| Problem | Cause | Fix |
|---|---|---|
| ”Auth failed” or “Not authorized” | Credentials expired or revoked | Reconfigure the hive from the expert page |
| Tool call times out | Slow external service or overly broad query | Narrow the query (add date filters, limit results) |
| Wrong account data returned | Connected the wrong account during OAuth | Reconfigure and sign in with the correct account |
| Hive not loading / no tools available | Hive was added but not saved, or service is down | Re-save the expert; check service status |
Next Steps
Configuring Agent Tools
Set up credentials and integrations for your expert.
Custom MCP Servers
Connect your own MCP servers for custom APIs.
Expert Fields Reference
See all expert configuration fields.