---
title: "Connect through MCP"
description: "Connect an AI assistant to Brella with a Core API token and tools generated from its scopes."
lastModified: "2026-10-30"
---

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](https://docs.brella.io/agents#install-the-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](https://docs.brella.io/getting-started/token-scopes#create-a-token-and-configure-its-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:

| Setting | Value |
| --- | --- |
| Name | `brella` (or another recognizable name) |
| Transport | Streamable HTTP |
| Server URL | The endpoint copied from the Admin Panel; production uses `https://api.brella.io/api/mcp` |
| Authentication | Bearer token: your Core API organization token |

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.

```text
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.

| Tool pattern | Core operation | Required access |
| --- | --- | --- |
| `core_list_<resource>` | List records (`GET`) | Read |
| `core_get_<resource>` | Read one record (`GET`) | Read |
| `core_create_<resource>` | Create a record (`POST`) | Write with Create |
| `core_update_<resource>` | Update a record (`PATCH`) | Write with Update |
| `core_delete_<resource>` | Delete a record (`DELETE`) | Write with Delete |

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:

```json
{
  "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](https://docs.brella.io/reference) and [cookbook](https://docs.brella.io/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.

```shell
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

| Result | Meaning and next step |
| --- | --- |
| HTTP `401`, `invalid_token` | The bearer token is missing, invalid or expired. Check the credential and environment. |
| HTTP `403`, `mcp_disabled` | Turn on **Enable MCP use** for this token and save. |
| HTTP `405` on `GET /api/mcp` | The endpoint accepts MCP requests over POST and offers no GET stream. Use a compatible transport. |
| Empty `tools/list` | Check associated scopes, Enabled, permissions and supported actions. |
| Tool result with `isError: true` | Read its text. An unknown tool may reflect missing or changed permissions; a Core API refusal includes its HTTP status and error body. |
| Tool error containing `404` | Check the event, record and row restrictions; inaccessible targets behave as not found. |
| HTTP `429`, or a tool error containing `429` | Slow down and follow [rate-limit and retry guidance](https://docs.brella.io/concepts/rate-limits). |
| JSON-RPC `error` | Fix the protocol request, method or parameter shape before retrying. |

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](https://docs.brella.io/cookbook/before-you-write) as a direct API integration. MCP does not change invitation, replacement, cancellation or deletion side effects.