events/list still names the events, and a poll, a stream, or a subscription is refused.
Discovery
The server advertises issue events in its discovery result. On revision2026-07-28, server/discover lists the extension under capabilities.extensions with no settings to configure:
events/list then names every event, with a short description and the JSON Schema for its arguments and for its payload. It describes the webhook profile, so each event’s delivery is ["webhook"]; polling and streaming read the same events:
events/list answers on every protocol revision the server speaks. Polling and streaming need revision 2026-07-28; the initialize handshake revisions carry the webhook methods only, and initialize names no events capability.
Event types
Every event carries the same bounded summary, frozen when Sazabi recorded it:
Polling
events/poll answers one bounded page per request and keeps no server-side state, so the client owns the cursor and stopping polling ends the watch. There is no subscription to create and nothing to unsubscribe.
Send the request on revision 2026-07-28, with the standard Mcp-Method and Mcp-Name headers. Mcp-Name must name the same event as params.name:
maxEvents asks for another count. hasMore says another page is ready now; nextPollMs says how long to wait when it is not.
Pushing over a held-open stream
events/stream takes the same params as a poll without maxEvents, and answers with a text/event-stream response the server keeps open. The first journal read decides admission: anything refused before that point is an ordinary JSON-RPC error and no stream opens.
Frames are JSON-RPC notifications, each carrying the request id as _meta["io.modelcontextprotocol/subscriptionId"]:
A stream ends normally when its 30 minutes are up, when the OAuth token that opened it expires, or when the server drains for a deploy. The final result is empty, so a client reconnects from the last cursor it saw rather than treating the end as a failure.
events/stream holds one subscription per request. Frames are delivered at least once, so deduplicate on eventId.
Webhook deliveries
events/list, events/subscribe, and events/unsubscribe deliver events to an HTTPS callback you control. Webhooks replay nothing: delivery starts with the next event after the subscription activates.
Only a signed-in person can subscribe, so this is the one mode a secret key cannot use. A project-scoped credential contributes its project; arguments carry the filters.
whsec_ followed by your base64-encoded key, which must decode to 24 to 64 bytes.
The answer names the subscription and the time to refresh it by:
refreshBefore to keep it. events/unsubscribe ends it and stops its queued deliveries, and answers the same whether or not the subscription existed.
Verifying the callback
Nothing is stored or activated until your endpoint accepts a signed challenge. The server sends a POST whose body is:Signed deliveries
Each delivery is one JSON POST with these headers:
The body is the event with
cursor fixed at null:
410 and 413 end that delivery without a retry; other failures retry, up to eight attempts, with the same bytes and a fresh timestamp and signature. Because an attempt can land twice, deduplicate on eventId.
Authentication and project scope
The server accepts the same credentials here as for tools: an OAuth sign-in, or a secret key in theX-Sazabi-Secret-Key header. Reads and streams accept both; webhook subscriptions accept only a signed-in person.
A project is chosen by projectId in arguments. A project-scoped secret key that omits it reads its own project; naming another project is refused. Filters narrow the events by severities, componentIds, and types.
Every read is authorized as an ordinary issue read for the caller at that moment, so events follow issue visibility rather than notification settings: a person who loses access to a project stops receiving its events on their next read, and an event is never delivered on cached authority.
Cursors, replay, and gaps
A cursor is an opaque position, never a credential: it is bound to the organization, project, event, and filters that produced it.- First read. A
cursorthat is null or absent starts at the newest event and returns no history. - Progress. Every answer advances the cursor, including a read that returns nothing, so a quiet stream or a poll that found nothing still moves forward.
- Replay. A stream reconnects from the last cursor it saw and replays what happened since. Replay is at least once.
- Gaps. Events are retained for seven days per project, up to 10,000 events. A cursor older than that is past retention, and the answer (or the
notifications/events/activeframe) setstruncated: trueand resumes from the oldest event still retained. Some events were missed; nothing replays them. - Webhooks. Deliveries never replay history. The subscription’s cursor is
nullwhen it is created.
Without promising more
Each mode delivers the same events. What each one does not do:
None of the modes promise exhaustive issue history or exactly-once execution of anything your agent does in response. None of them grant access: every read, page, and reconnect is authorized again.
Errors
Further reading
MCP server
The protocol reference, authentication, and tool surfaces.
Issues
What issues are and how the agent works them.