Connect through MCP

Connect an AI assistant to Brella with a Core API token and tools generated from its scopes.

Brella’s MCP server lets an AI assistant read or update event data through the permissions already configured on a Core API token. Each tool calls the Core API for that token’s organization. The same event boundaries, field selections, restrictions and write rules apply.

Use a client that supports remote Streamable HTTP MCP with bearer-token authentication. The server returns JSON responses; it does not provide an SSE stream. The Brella Core API skill adds workflows and reporting templates, and is optional for connecting.

1. Prepare the token

An organization administrator configures access in Admin Panel → API:

1. Create or review the required scopes in Scopes. For reporting, use Read access and narrow the selected events, fields, filters and related data to the report’s needs. The Read only preset initially selects all readable fields, filters and related data.
2. Open Organization tokens, then create a token or edit the intended token. In Associated scopes, select the scopes it should use. A token can have only one scope per primary resource.
3. In Token settings, turn on Enable MCP use, then save. MCP is off by default, including for existing tokens.
4. Copy the MCP endpoint displayed in the drawer. Securely save the token value when creating or rotating it; the existing secret cannot be retrieved later.

Follow Configure token scopes for the full setup. Scopes can be shared: changing one affects every token associated with it. Create a separate scope when the assistant needs a different policy from another integration.

2. Configure your MCP client

Add a remote MCP server in your client’s connection settings:

For clients with custom header settings, send Authorization: Bearer <core-api-token>. Use the corresponding sandbox endpoint for a sandbox token. A legacy Integration API key will not work.

Store the token in the client’s secret store or supported environment-variable configuration. Do not paste it into a chat, commit it to a project, or include it in generated reports. Configuration file formats vary by client; use its documented remote-server and secret settings.

Authentication differs by endpoint: direct /api/core requests use Brella-API-Access-Token; /api/mcp requests use Authorization: Bearer …. Enabling or disabling MCP does not change the token’s direct Core API access.

3. Discover and verify access

Connect the client and refresh its tools. The server identifies itself as brella-core-api. Ask the assistant to inspect the available Brella tools, then perform one small read against an event you have authorized.

Inspect the available Brella tools and their schemas. List one page of sponsors
for event EVENT_ID, using a page size of 5. Report the returned fields and any
access gaps before preparing the sponsor report.

This prompt requires a Sponsor scope with Read access to that event. An empty tool list can be a valid connection with no enabled, usable scopes. A missing tool is not a reason to try a different credential or route: ask the administrator for the specific access needed.

The server advertises no tool-list change notifications. After an administrator changes scopes, refresh tool discovery or reconnect your client. Calls continue to enforce current permissions.

Tools and arguments

Tool names follow the resource’s API name with dashes replaced by underscores: for example, sponsor-categories becomes core_list_sponsor_categories. Clients may add their own prefix when displaying tools.

Only supported, authorized actions appear. For example, a Read-only scope has no write tools, and an Event delete tool is available only in a sandbox with the necessary permission. A scope restricted to specific primary records cannot advertise a create action the Core API would refuse.

Always inspect the discovered input schema:

• Organization: derived from the token. Do not supply an organization_id to switch organizations.
• Event: event-level tools require event_id; organization-level tools omit it. A listed tool does not imply access to every event.
• Record: get, update and delete require id. Use the returned Brella ID.
• Pagination: list tools accept page: { "number": 1, "size": 30 }. The default size is 30 and the maximum is 100. Continue through the response’s meta.current_page and meta.total_pages.
• Filters: list tools expose permitted query fields. Required filters, such as benchmark comparison_event_ids, remain required and are exposed on get tools too. Follow the schema’s types; advertised filter values are strings.
• Related data: list and get tools accept an include array when the scope allows related data, using the advertised dashed or aliased names. Create, update and delete do not accept include.
• Writes: create and update expose the scope’s mapped writable parameter names. Structured inputs retain their object or array shape. Delete takes the target IDs, with no write body.

For example, a Sponsor list tool with Read access to name and the category association can accept these illustrative arguments:

{
  "event_id": "319986",
  "page": { "number": 1, "size": 5 },
  "include": ["category"]
}

Successful reads return the Core API JSON payload as text content in the MCP result. Read fields, write-response fields and included objects still depend on the scope. An omitted field is unavailable, not zero. The resource references and cookbook explain the underlying data and write effects.

Check the endpoint directly

For connection diagnostics, this read-only request discovers tools. Set BRELLA_API_BASE_URL to the approved API origin and load BRELLA_API_ACCESS_TOKEN from your secret store first. Do not enable shell tracing or log the authorization header.

curl --fail-with-body --request POST \
  --url "${BRELLA_API_BASE_URL}/api/mcp" \
  --header "Authorization: Bearer ${BRELLA_API_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The endpoint also supports the initialize lifecycle used by MCP clients, ping, and stateless server/discover. It keeps no session state. It exposes tools, without MCP resources, prompts, sampling or server-initiated messages.

Errors and retries

An HTTP 200 response alone does not prove a tool succeeded: inspect result.isError and any top-level JSON-RPC error. As with direct API calls, inputs outside the writable allowlist can be ignored; verify critical changed values.

MCP requests have token and IP rate limits. Executed tools also pass through Core API limits, so coordinate them with integrations sharing the token or IP. A batch is not a transaction: earlier writes can succeed even if a later entry fails. The default maximum is 50 batch entries; larger batches are rejected before execution. After a timeout or uncertain write, reconcile existing records before retrying.

Change or revoke access

• Turn off Enable MCP use and save to stop MCP access while keeping direct Core API access.
• Remove an associated scope from one token to remove that token’s access to the resource.
• Editing, disabling or deleting a shared scope affects every associated token, including direct API integrations. Review Associated tokens first.
• Rotate the token to invalidate its old secret, then update the client’s saved credential. Delete the token to revoke that credential entirely; shared scope definitions remain available to other tokens.

For writes, use the same plan, execute and verify workflow as a direct API integration. MCP does not change invitation, replacement, cancellation or deletion side effects.