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

# MCP issue events

> Read a project's issue events over the Model Context Protocol by polling, by a held-open stream, or by signed webhook deliveries.

Issue events announce what happens to issues in a project: an issue was created, changed in a way Sazabi announces, resolved, ignored, or reopened. A client connected to the [Sazabi MCP server](https://docs.sazabi.com/reference/mcp-server.md) can read them three ways: polling, holding a stream open, and receiving signed webhook deliveries.

Issue events are an extension served beside the MCP protocol, not part of it. The protocol revision decides how a request is framed and negotiated; the extension decides whether the server offers events at all. A client that does not ask for events loses nothing: tools, authentication, and errors behave the same.

Issue events are enabled per project. In a project without them, `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 revision `2026-07-28`, `server/discover` lists the extension under `capabilities.extensions` with no settings to configure:

```json theme={"system"}
{
  "capabilities": {
    "tools": {},
    "extensions": {
      "io.modelcontextprotocol/events": {}
    }
  }
}
```

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

```json theme={"system"}
{
  "events": [
    {
      "name": "issue.created",
      "description": "A new issue was announced in the project.",
      "delivery": ["webhook"],
      "inputSchema": {
        "$schema": "…",
        "type": "object",
        "properties": { "…": "…" }
      },
      "payloadSchema": {
        "$schema": "…",
        "type": "object",
        "properties": { "…": "…" }
      }
    }
  ]
}
```

`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

| Event | When it fires |
| - | - |
| `issue.created` | An issue was created in the project. |
| `issue.updated` | An issue changed in a way Sazabi announces: material, paced updates rather than every edit. |
| `issue.resolved` | An issue was resolved. |
| `issue.ignored` | An issue was ignored. |
| `issue.reopened` | An issue was reopened. |

Every event carries the same bounded summary, frozen when Sazabi recorded it:

```json theme={"system"}
{
  "eventId": "0f8d1c1e-4d5a-4a3f-9a1e-7c2b6a9d1f30",
  "name": "issue.resolved",
  "timestamp": "2026-11-18T14:02:11.480Z",
  "data": {
    "sourceEventId": "6a1d2f24-8c33-4b1e-9f2a-2d7c4b0e5a11",
    "occurredAt": "2026-11-18T14:02:11.402Z",
    "issue": {
      "id": "3c7f9b52-1a4e-4a8e-8f0d-5b2c9e6a4d17",
      "projectId": "b1a0f7c4-2d63-4f5e-9c8a-0e1d3b7a6c92",
      "name": "Checkout latency above 2s on /cart",
      "status": "resolved",
      "severity": "high",
      "types": ["performance"],
      "componentId": "9d2e1c40-6b7a-4f39-8a11-3c5e8f2b7a04",
      "componentName": "checkout-api",
      "url": "https://app.sazabi.com/issues/3c7f9b52-1a4e-4a8e-8f0d-5b2c9e6a4d17"
    },
    "actor": { "type": "user" },
    "note": null
  }
}
```

The summary never carries the agent prompt or the report. Read those with the issue-reading tools.

## 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`:

```json theme={"system"}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "events/poll",
  "params": {
    "name": "issue.resolved",
    "arguments": {
      "projectId": "b1a0f7c4-2d63-4f5e-9c8a-0e1d3b7a6c92",
      "severities": ["high", "critical"]
    },
    "cursor": null,
    "maxEvents": 50,
    "maxAgeMs": 3600000,
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {
        "name": "my-agent",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/clientCapabilities": {
        "extensions": { "io.modelcontextprotocol/events": {} }
      }
    }
  }
}
```

The answer holds the events oldest first, the cursor to send next, and how long to wait before asking again:

```json theme={"system"}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "complete",
    "events": [
      {
        "eventId": "0f8d1c1e-4d5a-4a3f-9a1e-7c2b6a9d1f30",
        "name": "issue.resolved",
        "timestamp": "2026-11-18T14:02:11.480Z",
        "data": {
          "occurredAt": "2026-11-18T14:02:11.402Z",
          "issue": {
            "id": "3c7f9b52-1a4e-4a8e-8f0d-5b2c9e6a4d17",
            "status": "resolved"
          }
        }
      }
    ],
    "cursor": "eyJ2IjoxLCJ0eCI6Mjg4NDQxOTcsInNxIjo3fQ",
    "truncated": false,
    "hasMore": false,
    "nextPollMs": 15000
  }
}
```

A page returns at most 100 events, 50 unless `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"]`:

| Frame | Meaning |
| - | - |
| `notifications/events/active` | The stream is open, with the cursor it starts from. It repeats with `"truncated": true` when events after the previous cursor are no longer retained. |
| `notifications/events/event` | One event, with the cursor to reconnect from. |
| `notifications/events/heartbeat` | The stream is alive and the cursor has advanced, at least every 15 seconds. |
| `notifications/events/error` | A read failed; the stream stays open and retries. |
| `notifications/events/terminated` | The subscription ended: authorization was lost, reads kept failing, or the client stopped reading. |

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.

```json theme={"system"}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "events/subscribe",
  "params": {
    "name": "issue.resolved",
    "arguments": {
      "projectId": "b1a0f7c4-2d63-4f5e-9c8a-0e1d3b7a6c92",
      "types": ["performance"]
    },
    "delivery": {
      "mode": "webhook",
      "url": "https://agent.example.com/hooks/sazabi",
      "secret": "whsec_PLACEHOLDER_BASE64_KEY"
    },
    "cursor": null
  }
}
```

The secret is a Standard Webhooks signing secret: `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:

```json theme={"system"}
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "id": "5b0d2b6e-7d0a-4a92-9a3e-1c4f8b2d6e71",
    "refreshBefore": "2026-11-25T14:02:11.402Z",
    "cursor": null,
    "truncated": false
  }
}
```

Subscribing again with the same project, event, filters, and URL refreshes the same subscription, and the id stays the same. A subscription lasts at most seven days and at least one hour; refresh before `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:

```json theme={"system"}
{ "type": "verification", "challenge": "9d1f0b7c88e04b1e" }
```

Answer with a 2xx and a JSON body naming the same challenge. An endpoint that fails the challenge is not activated. The URL must be HTTPS; redirects are refused and the addresses it resolves to must be public.

### Signed deliveries

Each delivery is one JSON POST with these headers:

| Header | Contents |
| - | - |
| `webhook-id` | The event's `eventId`, stable across attempts. |
| `webhook-timestamp` | The attempt's Unix time in seconds. |
| `webhook-signature` | `v1,` and the base64 HMAC-SHA256 of `<webhook-id>.<webhook-timestamp>.<body>`, keyed with your decoded `whsec_` secret. Two signatures are sent, space-separated, while a rotated key is retired. |
| `X-MCP-Subscription-Id` | The subscription the delivery belongs to. |

The body is the event with `cursor` fixed at `null`:

```json theme={"system"}
{
  "eventId": "0f8d1c1e-4d5a-4a3f-9a1e-7c2b6a9d1f30",
  "name": "issue.resolved",
  "timestamp": "2026-11-18T14:02:11.480Z",
  "data": {
    "occurredAt": "2026-11-18T14:02:11.402Z",
    "issue": {
      "id": "3c7f9b52-1a4e-4a8e-8f0d-5b2c9e6a4d17",
      "status": "resolved"
    }
  },
  "cursor": null
}
```

A delivery is at most 256 KiB and its callback has 10 seconds to answer. A 2xx acknowledges it; `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 the `X-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 `cursor` that 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/active` frame) sets `truncated: true` and resumes from the oldest event still retained. Some events were missed; nothing replays them.
* **Webhooks.** Deliveries never replay history. The subscription's cursor is `null` when it is created.

## Without promising more

Each mode delivers the same events. What each one does not do:

| Mode | Does not |
| - | - |
| Polling | Push. It answers when you ask, at the cadence `nextPollMs` and your own backoff suggest. It is not exhaustive issue history: an event that was never one Sazabi announces does not appear, and nothing older than the retention window is readable. |
| Streaming | Survive indefinitely. It ends after 30 minutes or when authority is lost, and a client reconnects. A credential holds five streams at once. Events may repeat across a reconnect. |
| Webhooks | Replay or guarantee exactly one attempt. A retry can deliver an event twice, and events are delivered as they are queued rather than sorted by time. A subscription is a grant you refresh, not a permanent endpoint. |

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

| Code | Meaning |
| - | - |
| `-32602` | Invalid params: bad filters, an unknown argument, or a project the credential may not name. |
| `-32020` | The `Mcp-Name` header is missing or names a different event than `params.name`. |
| `-32023` | Unknown event name. |
| `-32024` | Not permitted: the caller cannot read this project, the project has no issue events, or a secret key tried to subscribe. |
| `-32025` | Resource exhausted: a stream limit or a rate limit. |
| `-32015` | The callback endpoint failed its verification challenge, with the reason in `data.reason`. |

## Further reading

> [card] [MCP server](https://docs.sazabi.com/reference/mcp-server.md)
>
> The protocol reference, authentication, and tool surfaces.

> [card] [Issues](https://docs.sazabi.com/detect/issues.md)
>
> What issues are and how the agent works them.


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