> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trybrein.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events over MCP

> An agent subscribes to what happens in Brein and receives it as soon as it happens.

An MCP client can **subscribe** to a Brein event and receive it on its server as soon as it happens, without polling. Brein implements **MCP Events** in webhook mode, as ChatGPT supports it. MCP Events is still a draft of the specification (SEP-3415), so names may change.

A subscription is a [Destination](/api/destinations) created by an agent: same signed delivery, same retries, same address checks.

## How it is announced

With protocol `2026-07-28`, the `server/discover` result carries `"events": {}` in `capabilities`. The methods use the same endpoint and authentication as the tools. They answer for your credential's primary workspace.

## `events/list`

Returns the fourteen events of the [catalog](/api/events#catalog). Each has `name`, `description`, `delivery: ["webhook"]`, `inputSchema` (the subscription arguments) and `payloadSchema` (the schema of `data`).

The only argument is optional: `subject`, to receive only one object's events (`opportunity/<id>`).

## `events/subscribe`

```json theme={"theme":"github-light"}
{
  "name": "opportunity.moved",
  "arguments": { "subject": "opportunity/7b2c…" },
  "delivery": { "mode": "webhook", "url": "https://your-agent.example/brein", "secret": "whsec_…" },
  "cursor": null,
  "ttlMs": 604800000
}
```

| Field | Rule |
| - | - |
| `delivery.url` | Public `https`. Brein verifies it before accepting (below). |
| `delivery.secret` | You choose it: `whsec_` and base64 of 24 to 64 bytes. Brein signs with it. |
| `ttlMs` | How long it lasts. Omitted, 7 days; `null`, 30 days; a number is clamped between 1 hour and 30 days. |
| `cursor` | Brein does not replay history: it always answers `cursor: null`. To recover what you missed, [read the ledger](/api/events#read-the-ledger). |

It returns `{ "id", "refreshBefore", "cursor": null, "truncated" }`. Subscribe again before `refreshBefore` with the same values to renew. The `id` comes from who you are, the address, the event and the arguments: subscribing again with the same values **renews** instead of duplicating, and re-enables one that was turned off. A new secret replaces the old one; for 24 hours Brein signs with both.

A person subscribes, through their MCP client; an API key cannot. Not allowed in a test workspace: nothing leaves Brein from there.

## Address verification

Before accepting, Brein sends to your `url`:

```json theme={"theme":"github-light"}
{ "type": "verification", "challenge": "…" }
```

signed with your secret and with the `X-MCP-Subscription-Id` header. Answer `2xx` with `{ "challenge": "<the same value>" }` within 10 seconds. A verified address is not verified again for 24 hours.

## `events/unsubscribe`

The same `name`, `arguments` and `delivery` (without `secret`). Returns `{}`, even if it no longer existed. Delivery stops and history is kept.

## What you receive

```http theme={"theme":"github-light"}
POST /brein HTTP/1.1
content-type: application/json
webhook-id: 4d6f0c2e-6a1b-5f7e-9c3d-2b8a7e1f0a55
webhook-timestamp: 1792097051
webhook-signature: v1,…
x-mcp-subscription-id: 3f1c…

{ "eventId": "4d6f0c2e-…", "name": "opportunity.moved", "timestamp": "2026-10-15T18:04:11.000Z", "data": { … }, "cursor": null }
```

`eventId` is the event `id` in the ledger and does not change between retries. Verify the signature as for a [Destination](/api/destinations#verify-the-signature). An event can arrive more than once and out of order.

| Your response | What Brein does |
| - | - |
| `2xx` | Delivered. |
| `410` | Turns the subscription off. |
| `413` | Drops that event and continues with the rest. |
| Anything else, or no answer in 10 s | Retries on the Destination schedule, about 75 hours. |

When the subscription expires, Brein stops delivering what is pending.

## Errors

| JSON-RPC code | When | `data.reason` |
| - | - | - |
| `-32602` | Invalid parameters. | `unknown_event`, `invalid_arguments`, `secret_invalid`, `delivery_mode` |
| `-32015` | Your address failed verification. | `challenge_failed`, `timeout`, `url_rejected` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.