Connect an AI assistant to your organization's Brella data through MCP, the Model Context Protocol. An organization token's scopes control which events, records, fields and actions the assistant can use.
Before you start
You need to be an organization admin, with API access enabled for your organization.
Use an MCP client that supports a remote Streamable HTTP connection with bearer-token authentication.
Decide which data the assistant needs and whether it needs to make changes. Start with read access for reporting.
Create a separate organization token for the assistant so you can change or remove its access independently.
For scope setup and examples, see Give partners scoped API access with organization tokens.
Where to find it
Open Organizations, select Launch on your organization, then open API > Organization tokens.
Prepare the token
Select Create token, or select Edit on an existing token.
In Token settings, enter a Name that identifies the assistant.
Optional: choose an Expires date.
Open Associated scopes and select the scopes the assistant needs.
Return to Token settings and turn on Enable MCP use.
Copy MCP endpoint.
Select Create token, or Save when editing.
For a new token, select Copy to clipboard in Store your token and store the value in a password manager.
Enable MCP use is off for new tokens. Core API access remains available when MCP is off.
Brella shows the token value only at creation or rotation. If you no longer have the value, open Token settings > Token security and rotate the token. Update every connection using the old value.
Connect the assistant
Follow your MCP client's setup instructions and supply these values:
Server URL: the MCP endpoint copied from the admin panel.
Connection type: Streamable HTTP.
Authentication: bearer token, using the organization token's value.
If the client asks for an HTTP header, use Authorization with the value Bearer <organization token>.
Keep the token in the client's credential settings. Do not paste it into a chat message or a shared document.
After connecting, check the available actions. Try a read request for one known record in an event covered by the scope. Compare the result with the admin panel before using a larger report.
Control what the assistant can access
The assistant receives only the actions permitted by the token's enabled scopes. Read results include permitted fields; writes accept permitted inputs. Event access and data restrictions still apply.
A read-only scope cannot create, update or delete records.
Read only initially selects all readable fields, allowed filters and related data. Choose Custom to narrow those selections.
Read + write grants supported write actions except Delete. Select individual actions and fields if the assistant needs less access.
A token can have one scope per resource.
Shared scope changes apply to every token using the scope, including other integrations and assistants.
Before saving a scope change, check its Associated tokens tab. To change only one assistant's access, give its token a separate scope.
Remove or replace access
Stop MCP access: edit the token, turn off Enable MCP use and select Save. Direct Core API use of that token remains available.
Remove access to a resource: clear its scope under the token's Associated scopes and select Save. The scope remains available for other tokens.
Replace the token value: open Token settings > Token security, select Rotate token, then Rotate. The old value stops working immediately. Copy the new value and update the client.
Remove the token: select Delete token, then Delete. All connections using that token lose access. Shared scopes remain.
Troubleshooting
The connection returns invalid_token or error 401
The token is invalid or expired. Use the current organization token value with bearer authentication. A personal API key does not work for MCP.
The connection returns mcp_disabled or error 403
Open the token's Token settings, turn on Enable MCP use and select Save.
An expected action is missing
Check the token's Associated scopes. The resource needs an enabled scope that grants the action. An available action also depends on what that resource supports.
The assistant cannot access an event or field
Check Event access, Readable fields, Writable fields and Data restrictions in the scope. Save only the access the assistant needs.
Opening the endpoint in a browser returns error 405
The endpoint accepts MCP requests by POST. Configure it in your MCP client instead of opening it as a web page.