Events over MCP

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 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. 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>).

{
  "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.

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:

{ "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

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

Start

Connect

Work with your agent

Integrations

Trust

For developers

Events over MCP

How it is announced

`events/list`

Address verification

`events/unsubscribe`

What you receive

Errors

​How it is announced

​events/list

​events/subscribe

​Address verification

​events/unsubscribe

​What you receive

​Errors

How it is announced

`events/list`

`events/subscribe`

Address verification

`events/unsubscribe`

What you receive

Errors