diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a8cf76c..20c18ec 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ This Working Group welcomes contributions from anyone interested in server-initiated notifications and event-driven patterns in MCP. You can participate by: -- Joining discussions in the [#triggers-and-events-wg Discord channel](https://discord.com/channels/1358869848138059966/1479499641304387624) (info on joining the Discord server [here](https://modelcontextprotocol.io/community/communication#discord)) +- Joining discussions in the [#tasks-events-wg Discord channel](https://discord.com/channels/1358869848138059966/1479499641304387624) (info on joining the Discord server [here](https://modelcontextprotocol.io/community/communication#discord)) - Opening or commenting on [GitHub Discussions](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions) in the main MCP repo - Sharing experimental findings from your own implementations - Contributing to proposals and reference implementations @@ -13,13 +13,13 @@ This Working Group welcomes contributions from anyone interested in server-initi | Channel | Purpose | Response Expectation | | :--- | :--- | :--- | -| [Discord #triggers-and-events-wg](https://discord.com/channels/1358869848138059966/1479499641304387624) | Quick questions, coordination, async discussion | Best effort | +| [Discord #tasks-events-wg](https://discord.com/channels/1358869848138059966/1479499641304387624) | Quick questions, coordination, async discussion | Best effort | | [GitHub Discussions](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions) | Meeting notes, long-form technical proposals, experimental findings | Weekly triage | | This repository | Living reference for proposals, findings, and reference implementations | Updated after meetings | ## Meetings -The WG holds a weekly 30-minute working session for technical discussion and proposal review. Scheduling is posted in the [#triggers-and-events-wg Discord channel](https://discord.com/channels/1358869848138059966/1479499641304387624). +The WG holds a weekly 30-minute working session for technical discussion and proposal review. Scheduling is posted in the [#tasks-events-wg Discord channel](https://discord.com/channels/1358869848138059966/1479499641304387624). Meeting norms: @@ -28,7 +28,7 @@ Meeting norms: ## Decision-Making -As a Working Group, we operate by **consensus** within the scope defined by our [charter](https://modelcontextprotocol.io/community/triggers-events/charter). Spec changes require WG consensus followed by Core Maintainer approval through the SEP process. See the charter's Authority & Decision Rights table for specifics. +As a Working Group, we operate by **consensus** within the scope defined by our [charter](https://modelcontextprotocol.io/community/working-groups/tasks-events). Spec changes require WG consensus followed by Core Maintainer approval through the SEP process. See the charter's Authority & Decision Rights table for specifics. ## Contribution Guidelines diff --git a/README.md b/README.md index d1b78ec..e3f6474 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ -# Triggers & Events Working Group +# Tasks and Events Working Group -> ⚠️ **Experimental** — This repository is an incubation space for the Triggers & Events Working Group. Contents are exploratory and do not represent official MCP specifications or recommendations. +> ⚠️ **Experimental** — This repository is an incubation space for the Tasks and Events Working Group. Contents are exploratory and do not represent official MCP specifications or recommendations. ## Mission -The Triggers & Events Working Group exists to define how MCP servers proactively notify clients of state changes. Today, clients learn about server-side updates by polling or holding an SSE connection open. This WG will specify a standardized callback mechanism — webhooks or similar — that lets servers push notifications when new data is available, with defined ordering guarantees that hold across all transports. +The Tasks and Events Working Group exists to define how MCP servers proactively notify clients of state changes. Today, clients learn about server-side updates by polling or holding an SSE connection open. This WG will specify a standardized callback mechanism — webhooks or similar — that lets servers push notifications when new data is available, with defined ordering guarantees that hold across all transports. -See the full [Working Group Charter](https://modelcontextprotocol.io/community/triggers-events/charter) for scope, authority, and operations. +See the full [Working Group Charter](https://modelcontextprotocol.io/community/working-groups/tasks-events) for scope, authority, and operations. ## Scope @@ -35,8 +35,14 @@ See the full [Working Group Charter](https://modelcontextprotocol.io/community/t | Role | Name | Organization | GitHub | | :--- | :--- | :--- | :--- | | Lead | Clare Liguori | Amazon Web Services | [@clareliguori](https://github.com/clareliguori) | -| Lead | Peter Alexander | Anthropic | [@pja-ant](https://github.com/pja-ant) | +| Lead | Peter Alexander | - | [@poita](https://github.com/poita) | +| Lead | Luca Chang | Amazon Web Services | [@LucaButBoring](https://github.com/LucaButBoring) | +| Lead | Caitie McCaffrey | Microsoft | [@CaitieM20](https://github.com/CaitieM20) | ## Repository Contents +| Extension | Stage | Specification | SEP | +| :--- | :--- | :--- | :--- | +| Events (`io.modelcontextprotocol/events`) | Beta | [`specification/beta/events/`](specification/beta/events/events.mdx) | [SEP-3415](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/3415-events-extension.md) | + This repository will hold proposals, reference implementations, and experimental findings as the WG's work progresses. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to participate. diff --git a/specification/beta/events/events.mdx b/specification/beta/events/events.mdx new file mode 100644 index 0000000..276700c --- /dev/null +++ b/specification/beta/events/events.mdx @@ -0,0 +1,852 @@ +--- +title: Events Extension +--- + +
+ + +**Stage**: Beta · **Extension identifier**: `io.modelcontextprotocol/events` · **Defined by**: [SEP-3415](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/3415-events-extension.md) + + +## Introduction + +Events lets an MCP client subscribe to things that happen in an upstream system, such as a Slack message, a GitHub push or a PagerDuty incident, and have an agent react when they occur without the user being present. + +A server lists its event types with `events/list`. Each event type has a name, an `inputSchema` for subscription arguments, a `payloadSchema`, and the delivery modes it supports. A client subscribes with `(name, arguments)` and receives event occurrences of the form `{eventId, name, timestamp, data, cursor}`. There are three delivery modes, advertised per event type, and none is mandatory: poll (`events/poll`), push (`events/stream`) and webhook (`events/subscribe`). + +This extension is in **Beta**. Real usage is welcome, and breaking changes are expected to be rare and will be documented. The motivation, design rationale, open questions and non-normative SDK guidance are in [SEP-3415](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/3415-events-extension.md). + +## Specification + +This extension is defined for protocol revision `2026-07-28` and later. It relies on per-request client capabilities, `server/discover` and `subscriptions/listen`, which earlier revisions do not have. + +Two conventions apply throughout: + +- Every result this extension defines is a standard `Result` and carries `resultType: "complete"`. +- Error codes are referred to by name. [Error Handling](#error-handling) gives the numeric codes. + +### Extension Identifier + +This extension is identified as `io.modelcontextprotocol/events`. + +### Working Group and Extension Maintainers + +The extension is owned by the [Tasks and Events Working Group](https://modelcontextprotocol.io/community/working-groups/tasks-events). Its Extension Maintainers are the Working Group leads, currently Clare Liguori (@clareliguori), Peter Alexander (@poita), Luca Chang (@LucaButBoring) and Caitie McCaffrey (@CaitieM20). + +The extension was incubated in [`experimental-ext-triggers-events`](https://github.com/modelcontextprotocol/experimental-ext-triggers-events) and entered Beta through [SEP-3415](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/3415-events-extension.md). + +### Capability Negotiation + +Events is declared through [Extension Negotiation](https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning#extension-negotiation): the identifier appears as a key in the `extensions` field of capabilities, mapped to the extension's settings object. + +A server advertises event support in the capabilities it returns from `server/discover`: + +```jsonc +{ + "result": { + // Other response fields... + "capabilities": { + "extensions": { + "io.modelcontextprotocol/events": { + "listChanged": true, + }, + }, + }, + }, +} +``` + +The server's settings object has one member: `listChanged` (boolean, optional, default `false`), which says whether the server sends `notifications/events/list_changed` (see [Dynamic event types](#dynamic-event-types)). An empty settings object declares event support with no list-change notifications. + +A client MAY declare the same identifier with an empty settings object, in its per-request capabilities, to indicate that it understands the extension: + +```jsonc +{ + // Other request fields... + "params": { + "_meta": { + "io.modelcontextprotocol/clientCapabilities": { + "extensions": { + "io.modelcontextprotocol/events": {}, + }, + }, + }, + }, +} +``` + +**Fallback.** All `events/*` requests are client-initiated. A client MUST NOT send them to a server that has not advertised the extension, and a server that does not offer it answers any `events/*` request with `-32601` (Method not found). The only message this extension adds outside an `events/*` request is `notifications/events/list_changed`, which a client receives only if it opts in on a `subscriptions/listen` stream. Neither party changes its core protocol behavior when the other does not support Events. + +### Delivery Modes + +There are three delivery modes, with different subscription mechanisms. An event type advertises any non-empty subset of them. + +- **Poll.** The client calls `events/poll` with the event name, arguments and cursor. There is no separate subscribe step: the first poll with a `null` cursor bootstraps the subscription. The server holds no protocol-required state. +- **Push.** The client opens a long-lived `events/stream` request per subscription. The server delivers events on the request's response stream (Streamable HTTP) or as notifications on stdout (stdio). Closing or cancelling the request ends the subscription. Server state is scoped to the lifetime of the request. +- **Webhook.** The client calls `events/subscribe` to register a callback URL, and the server POSTs events to that URL as they occur. The subscription has a TTL negotiated at subscribe time: the client suggests a lifetime and the server grants one, possibly with no expiry (see [Subscription TTL](#subscription-ttl)). Unless it was granted no expiry, the client refreshes by calling `events/subscribe` again before the TTL expires. If it stops, the subscription expires and the server reclaims its resources. Webhook is designed for remote servers where a long-lived connection is impractical. + +The client SDK chooses the mode and runs the loop. The model sees only the events that arrive. + +### Listing Available Events + +#### Request: `events/list` + +```jsonc +// params (optional) +{ "cursor": "..." } // pagination +``` + +#### Response + +```jsonc +{ + "resultType": "complete", + "events": [ + { + "name": "email.received", + "description": "Fires when a new email arrives in the inbox", + "delivery": ["poll"], + "inputSchema": { + "type": "object", + "properties": { + "from": { + "type": "string", + "description": "Glob pattern for sender address", + }, + "subject_contains": { "type": "string" }, + "redact_pii": { + "type": "boolean", + "default": false, + "description": "Strip PII from event payloads", + }, + "include_body_preview": { + "type": "boolean", + "default": true, + "description": "Include a snippet of the email body", + }, + }, + }, + "payloadSchema": { + "type": "object", + "properties": { + "messageId": { "type": "string" }, + "from": { "type": "string" }, + "subject": { "type": "string" }, + "receivedAt": { "type": "string", "format": "date-time" }, + }, + }, + }, + { + "name": "incident.created", + "description": "Fires when a new PagerDuty incident is created", + "delivery": ["webhook", "push", "poll"], + "inputSchema": { + "type": "object", + "properties": { + "severity": { "type": "string", "enum": ["P1", "P2", "P3", "P4"] }, + "service": { "type": "string" }, + "deduplicate_window_seconds": { + "type": "integer", + "default": 0, + "description": "Suppress duplicate alerts within this window", + }, + }, + }, + "payloadSchema": { "...": "..." }, + "_meta": { "...": "..." }, // optional; same semantics as on Tool/Resource/Prompt + }, + ], + "nextCursor": "...", // present when more pages are available; same semantics as tools/list +} +``` + +- `delivery` lists the delivery modes the event type supports. It is any non-empty subset of `"poll"`, `"push"` and `"webhook"`. No mode is mandatory. A client that cannot use any of the listed modes cannot subscribe to the event type. +- `inputSchema` is a JSON Schema for valid subscription arguments. Arguments may be filters (which narrow the event stream), transforms (which modify payloads) or other server-defined configuration. This mirrors the `inputSchema`/`arguments` pairing on tools. As on tools, a property MAY carry an `x-mcp-header` annotation, which mirrors that argument into an HTTP header (see [Custom headers from subscription arguments](#custom-headers-from-subscription-arguments)). +- `payloadSchema` is a JSON Schema for `data` in delivered events. + +**Schema evolution.** A subscription can outlive the `events/list` response it was created from. Servers SHOULD therefore evolve an event type's `inputSchema` and `payloadSchema` additively for the lifetime of its `name`: + +- New optional fields MAY be added. +- Existing fields SHOULD NOT be removed, renamed or retyped. +- Enums SHOULD NOT be narrowed. +- `inputSchema` SHOULD NOT be tightened so that previously accepted `arguments` become invalid. A webhook refresh re-sends them, and would fail with `InvalidParams`. + +A breaking change SHOULD instead be published under a new event name and served alongside the old one for a migration period, after which the old name is removed (see [Event type removal and breaking changes](#event-type-removal-and-breaking-changes)). + +#### Dynamic event types + +If the set of available event types changes at runtime, or the descriptor of any of them changes (`description`, `delivery`, `inputSchema`, `payloadSchema`), a server that declared `listChanged: true` sends `notifications/events/list_changed`. Examples are a plugin being loaded, a data source being connected, or a schema gaining a field. The client SHOULD call `events/list` again to refresh its registry of event types. This is consistent with `notifications/tools/list_changed` and `notifications/resources/list_changed`. + +Like the core `list_changed` notifications, it is delivered only on a `subscriptions/listen` stream, and only when the client opted in. This extension adds one field to the `notifications` filter of `subscriptions/listen`: + +```typescript +export interface SubscriptionFilter { + // Other existing fields... + /** + * If true, receive notifications/events/list_changed. + */ + eventsListChanged?: boolean; +} +``` + +The server echoes `eventsListChanged` in `notifications/subscriptions/acknowledged` if it agrees to honor it. A server that did not declare `listChanged: true` omits it from the acknowledged filter. + +#### Event type removal and breaking changes + +When a server stops offering an event type, or changes its `inputSchema` or `payloadSchema` incompatibly in place (contrary to _Schema evolution_ above), existing subscriptions to that name no longer hold a valid contract. The server SHOULD end them with each mode's termination signal (see [Subscription Termination](#subscription-termination)): `notifications/events/terminated` on push streams, and a `terminated` envelope to webhook subscriptions. + +The `error` is: + +- `NotFound` with `data: {"kind": "event"}` when the type was removed. +- `Unsupported` with `data: {"feature": "payloadSchema" | "inputSchema", "reason": "schema_changed"}` when it was changed in place. + +It is not `Forbidden`, because the principal's access is unchanged. The client SDK therefore fetches `events/list` again and resubscribes against the current descriptor, and does not treat the termination as an authorization failure. Purely additive changes MUST NOT terminate subscriptions. + +Poll holds no server-side subscription to terminate. A poll against a removed name already returns `NotFound`. For an in-place change, a server that wants to force rediscovery MAY mint cursors that encode a schema epoch and answer a stale one with the same `Unsupported` error. Otherwise poll clients pick up the change on their next `events/list`. + +### Event Occurrences + +Each entry in a poll result's `events[]`, the params of `notifications/events/event`, and the body of a webhook event delivery is an `EventOccurrence`. Push notifications additionally carry the stream's subscription ID in `_meta` (see [Push-Based Delivery](#push-based-delivery)). Webhook delivery also sends control bodies that are not events (see [Non-event webhook bodies](#non-event-webhook-bodies)). + +| Field | Type | Required | Description | +| ----------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `eventId` | string | yes | Stable identifier of the upstream event, for deduplication within a subscription. | +| `name` | string | yes | Event type name. | +| `timestamp` | string (ISO 8601) | yes | When the event occurred. | +| `data` | object | yes | Payload that conforms to the event type's `payloadSchema`. | +| `cursor` | string \| null | no | Subscription position after this event. Push and webhook only; poll carries the cursor at the response level. `null` when the event type does not support replay (see [Cursor Lifecycle](#cursor-lifecycle)). | +| `_meta` | object | no | Reserved for protocol and extension metadata, consistent with `_meta` on other MCP types. Not governed by `payloadSchema`. | + +`eventId` identifies the upstream event and enables client-side deduplication within a subscription, for example across polls after a crash and restart. It is assigned by the server. When the upstream source provides a stable event identifier (a Stripe `evt_*`, a GitHub delivery GUID, a Kafka offset, a Gmail message ID), the server SHOULD use that value as `eventId`. The same upstream event surfaced by more than one path, such as a webhook emit and a poll backfill, then carries the same `eventId`, and deduplication works. Deduplication is scoped to a subscription (its `name` and `arguments`), whichever delivery mode carries it. One upstream event can match several subscriptions, such as "messages in this channel" and "messages from this person", and then arrives on each with the same `eventId`. Each subscription receives it: the same `eventId` on two different subscriptions is not a duplicate. A server SDK generates an `eventId` only when the author supplies none. + +### Poll-Based Delivery + +The client SDK calls `events/poll` at the interval the server recommends. This is a protocol-level operation, not an LLM tool call. + +```mermaid +sequenceDiagram + autonumber + participant SDK as Client SDK + participant Server as MCP Server + + loop every nextPollMs + SDK->>Server: events/poll {name, arguments, cursor} + Server-->>SDK: {events[], cursor, truncated, hasMore, nextPollMs} + end + Note over SDK: LLM invoked only when
events[] is non-empty +``` + +#### Request: `events/poll` + +Each `events/poll` request carries one subscription. A client with several subscriptions runs one poll loop per subscription. + +```jsonc +{ + "name": "email.received", + "arguments": { + "from": "*@anthropic.com", + "redact_pii": true, + }, + "cursor": null, // null = start from now + "maxAgeMs": 300000, // optional; do not replay events older than this many milliseconds (see Cursor Lifecycle) + "maxEvents": 50, // optional; cap events returned +} +``` + +#### Response + +```jsonc +{ + "resultType": "complete", + "events": [ + { + "eventId": "evt_001", + "name": "email.received", + "timestamp": "2026-02-19T15:30:00Z", + "data": { + "messageId": "msg_xyz", + "from": "dsp@anthropic.com", + "subject": "MCP spec review", + "receivedAt": "2026-02-19T15:29:58Z", + }, + }, + ], + "cursor": "historyId_99842", + "truncated": false, + "hasMore": false, + "nextPollMs": 30000, +} +``` + +- `cursor` is opaque to the client. The client stores it and passes it back on the next poll. In the request, `null` means "start from now": the server returns no events and a fresh cursor for later polls. In the response, the server MAY return `cursor: null` for an event type that does not support replay. The client then has nothing to persist and always polls with `null` (see [Cursor Lifecycle](#cursor-lifecycle)). +- `maxEvents` is an optional cap on the number of events returned. If more events are available than the cap, the server returns a partial batch with an intermediate cursor and sets `hasMore: true`. If it is omitted, the server uses its own default. +- `hasMore` says whether more events are available beyond the returned batch. When it is `true`, the client SHOULD poll again immediately with the updated cursor, ignoring `nextPollMs`, to drain the backlog. When it is `false`, the client waits `nextPollMs` before the next poll. +- `nextPollMs` lets the server adjust polling frequency, for example to back off when it is rate-limited upstream or to speed up when it sees activity. It is ignored when `hasMore` is `true`. It is a recommendation: a client MAY poll less often, for example because of its own scheduling limits. Polls carry no server state, so the only risk of polling slowly is a cursor that falls outside the upstream's retention window, which the server reports with `truncated: true`. Clients SHOULD apply a configurable floor (default 1000 ms) so that a misbehaving server cannot induce a tight loop. +- An empty `events` array means nothing happened. This is the common case and should be cheap. +- The server holds no protocol-required state per client. Each poll request is self-contained: the client provides the event name, arguments and cursor, and the server does not need to remember earlier polls to answer it. A server SDK MAY hold ephemeral derived state, such as a poll-lease table to drive lifecycle hooks, or a ring buffer of recent events for emit-only event types. Neither is required to answer a poll, both can be rebuilt, and neither is owed to any particular client (see [Appendix A](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/3415-events-extension.md#appendix-a-sdk-guidance-non-normative)). +- Errors (`NotFound`, `Forbidden`, `InvalidParams`, `Unsupported`) are returned as a standard JSON-RPC error response. There is no partial-success model, because each request carries one subscription. + +### Push-Based Delivery + +Push delivery uses a long-lived `events/stream` request, one per subscription. The client opens a stream for each subscription, and the server delivers events as they occur. The request is a standard JSON-RPC request with an `id`. The `id` enables cancellation with `notifications/cancelled`, and is echoed in `_meta` on every `notifications/events/*` message for this stream, so that a client can demultiplex concurrent streams on stdio. + +The stream follows the same conventions as the core `subscriptions/listen` stream: a confirmation notification comes first, every notification carries the subscription ID in `_meta`, and an empty result closes the stream gracefully. The mechanism differs by transport: + +- **Streamable HTTP.** The `events/stream` request is a POST that returns an SSE response stream. The client cancels by aborting the request stream (TCP close on HTTP/1.1, `RST_STREAM` on HTTP/2). No explicit cancellation message is needed. +- **stdio.** The `events/stream` request is written to stdin, and the server delivers events as JSON-RPC notifications on stdout. There is no connection to close, so the client cancels by sending `notifications/cancelled` with the request's `id`. + +The stream is logical: the sequence of messages tagged with this subscription's ID. On stdio it shares stdout with all other server messages. The stream carries only this subscription's `notifications/events/*` messages. It is not a general server-to-client channel. Other notifications (`notifications/tools/list_changed`, `notifications/resources/updated`, progress, logging) continue to use the mechanisms the core protocol provides, and are unaffected by this extension. + +```mermaid +sequenceDiagram + autonumber + participant SDK as Client SDK + participant Server as MCP Server + + SDK->>Server: events/stream {name, arguments, cursor} + activate Server + Server-->>SDK: notifications/events/active {cursor, truncated, heartbeatMs, _meta.subscriptionId} + loop as events occur + Server-->>SDK: notifications/events/event {eventId, name, timestamp, data, cursor, _meta.subscriptionId} + end + SDK->>Server: notifications/cancelled {requestId} (stdio)
or connection close (Streamable HTTP) + Server-->>SDK: StreamEventsResult (final frame) + deactivate Server +``` + +#### Request: `events/stream` + +```jsonc +// Streamable HTTP: POST to the MCP endpoint +// stdio: written to stdin +{ + "jsonrpc": "2.0", + "method": "events/stream", + "id": 1, + "params": { + "name": "email.received", + "arguments": { "from": "*@anthropic.com", "redact_pii": true }, + "cursor": null, + "maxAgeMs": 300000, + "heartbeatMs": 15000, // optional; suggested heartbeat interval (see Lifecycle) + }, +} +``` + +#### Event delivery + +If the subscription is invalid (`NotFound`, `Forbidden`, `InvalidParams`, `Unsupported`), the server responds immediately with a JSON-RPC error and no stream is opened. Otherwise the server confirms the subscription with `notifications/events/active`, which carries the granted heartbeat interval, and then delivers events as notifications. + +Every `notifications/events/*` message carries the JSON-RPC `id` of the parent `events/stream` request in `params._meta["io.modelcontextprotocol/subscriptionId"]`, the correlation key the core protocol defines for subscription streams. A client with several concurrent streams, especially on stdio where they all share one stdout, uses it to route notifications to the right stream. + +```jsonc +// Confirmation +{"jsonrpc":"2.0","method":"notifications/events/active","params":{"cursor":"historyId_99840","truncated":false,"heartbeatMs":15000,"_meta":{"io.modelcontextprotocol/subscriptionId":1}}} + +// Events as they occur +{"jsonrpc":"2.0","method":"notifications/events/event","params":{"eventId":"evt_001","name":"email.received","timestamp":"2026-02-19T15:30:00Z","data":{"messageId":"msg_xyz","from":"dsp@anthropic.com","subject":"MCP spec review"},"cursor":"historyId_99842","_meta":{"io.modelcontextprotocol/subscriptionId":1}}} + +// Transient per-occurrence error (stream stays open) +{"jsonrpc":"2.0","method":"notifications/events/error","params":{"error":{"code":-32603,"message":"UpstreamError","data":{"reason":"Gmail API 503"}},"_meta":{"io.modelcontextprotocol/subscriptionId":1}}} + +// Final frame when the server closes the stream (StreamEventsResult) +{"jsonrpc":"2.0","id":1,"result":{"resultType":"complete","_meta":{"io.modelcontextprotocol/subscriptionId":1}}} +``` + +`notifications/events/error` reports a recoverable failure, such as a single failed upstream fetch. The subscription stays active, and the server retries and resumes. Only `notifications/events/terminated` ends the subscription (see [Subscription Termination](#subscription-termination)). + +A gap, such as a cursor that fell outside the upstream's retention window, is not an error. The server sends a fresh `notifications/events/active` with `truncated: true` and a new cursor, and continues delivering (see [Cursor Lifecycle](#cursor-lifecycle)). + +On Streamable HTTP, notifications are SSE `data:` frames. When the server ends the stream it sends the `StreamEventsResult` as the final `data:` frame. When the client ends it by aborting the request stream, no result can be sent. On stdio, notifications are newline-delimited JSON messages on stdout. + +#### Lifecycle + +- **Stream termination.** The `StreamEventsResult` is an empty result that carries only `resultType` and the subscription ID in `_meta`, mirroring `SubscriptionsListenResult`. It carries no information. It satisfies the JSON-RPC requirement that every request gets a response, and all meaningful content is in the notifications before it. It is sent whenever the server can write a final frame: on Streamable HTTP only when the server initiates the close, and on stdio at the server's discretion. Clients MUST NOT depend on receiving it. +- **Heartbeat.** The server MUST send periodic keepalive messages on the push stream, so that the client can tell "nothing to send" from "the connection is dead". The heartbeat is `{"jsonrpc":"2.0","method":"notifications/events/heartbeat","params":{"cursor":"historyId_99850","_meta":{"io.modelcontextprotocol/subscriptionId":1}}}`. `cursor` is the position the server has checked up to, so the client's persisted cursor advances even when no events match (see [Cursor Lifecycle](#cursor-lifecycle)). It is `null` for event types that do not support replay. On Streamable HTTP the heartbeat is an SSE `data:` frame. The SSE comment form (`: keepalive`) is not used, because it cannot carry cursor state. The heartbeat also lets the server notice a client that has gone away, because a write to a dead connection fails, and release the subscription and any upstream resources behind it. +- **Heartbeat interval.** The client MAY suggest an interval in milliseconds with `heartbeatMs` in the `events/stream` params. The server grants one in `heartbeatMs` on every `notifications/events/active`, and the grant is authoritative. The server honors the suggestion within its own bounds, such as its CPU budget for idle streams or the idle timeout of its load balancer, and otherwise clamps it. Without a suggestion the server chooses, and 30 seconds is the recommended default. Each side SHOULD keep the interval below the idle timeouts of the intermediaries it knows about, such as the server's load balancer or the client's egress proxy, which commonly close idle connections after 60 to 100 seconds. The server sends a heartbeat whenever `heartbeatMs` passes without any other message on the stream. Clients SHOULD NOT apply their default request timeout to `events/stream`: the heartbeat is the liveness signal. A client that has received no message on the stream for three times the granted `heartbeatMs`, counted from `notifications/events/active`, SHOULD treat the stream as dead and reconnect with its cursor. On stdio, the client detects a dead server by end of file on stdout, so the heartbeat only advances the cursor, and a server MAY grant a longer interval there. +- **Cancellation.** On Streamable HTTP, the client aborts the request stream. On stdio, the client sends `notifications/cancelled` with the `requestId` of the `events/stream` request. In both cases the server MUST stop delivering events and release the associated resources. On stdio, the server MAY then send the `StreamEventsResult`. The core protocol says servers SHOULD NOT respond to cancelled requests, so omitting it is the expected behavior. On Streamable HTTP, the abort is the terminal signal and no result is sent. +- **Concurrent streams.** A client MAY hold several concurrent `events/stream` requests open, one per subscription. To add a subscription it opens another stream, and to remove one it cancels only that stream. On HTTP/1.1 each stream consumes a TCP connection, so a client with many subscriptions effectively depends on HTTP/2 multiplexing. On stdio, concurrent streams share stdout and are demultiplexed by `_meta["io.modelcontextprotocol/subscriptionId"]`. Server SDKs MUST exempt `events/stream` from any general cap on concurrent requests, because each push subscription is a long-lived request that does not complete until it is cancelled. +- **Reconnection after failure.** If the connection drops (HTTP) or the server stops sending (stdio), the client sends a new `events/stream` with the same subscription and its last known cursor. Clients SHOULD wait a random jitter before reconnecting, so that a server restart does not bring every client back at the same moment. + +#### Cursor advancement + +Each event notification on the push stream includes a `cursor` field, which is the subscription's position after this event. The client tracks the latest cursor per subscription for use when it reconnects. The server MAY send `cursor: null` for event types that do not support replay (see [Cursor Lifecycle](#cursor-lifecycle)). + +### Webhook-Based Delivery + +Webhook delivery is for remote MCP servers where a long-lived connection (push) or frequent polling is impractical. The server POSTs events to a callback URL that the client provides. Webhook subscriptions are TTL-scoped: the client suggests a lifetime, the server grants one, and the subscription expires if the client stops refreshing before the granted expiry. The TTL is the server's resource-control knob. Short grants keep subscriptions as in-memory soft state that expiry cleans up. Long or no-expiry grants shift the durability and cleanup burden onto the server (see [Subscription TTL](#subscription-ttl)). + +The callback URL does not need to be the client itself. A common deployment is a forward proxy that receives webhooks and serves events to clients by poll or push: + +``` +Upstream → MCP Server → webhook POST → Forward Proxy ← Client (poll or push) +``` + +```mermaid +sequenceDiagram + autonumber + participant SDK as Client SDK + participant Server as MCP Server + participant Hook as Webhook Endpoint + + SDK->>Server: events/subscribe {name, arguments, delivery: {url, secret}, cursor, ttlMs} + Server-->>SDK: {id, refreshBefore, cursor, truncated} + loop as events occur + Server->>Hook: POST {eventId, name, timestamp, data, cursor} + Standard Webhooks signature + Hook-->>Server: 200 OK + Hook--)SDK: deliver event (implementation-defined,
e.g. forward proxy → poll/push) + end + loop before each refreshBefore + SDK->>Server: events/subscribe (same key, refreshes TTL) + Server-->>SDK: {refreshBefore', cursor, deliveryStatus} + end + opt explicit teardown (else: stop refreshing → TTL expiry) + SDK->>Server: events/unsubscribe {name, arguments, delivery: {url}} + Server-->>SDK: (ack) + end +``` + +#### Subscribing: `events/subscribe` + +Unlike poll and push, webhook delivery needs an explicit subscribe step, because the server has to know where to POST events. `events/subscribe` is idempotent: calling it again with the same subscription key (see [Subscription identity](#subscription-identity)) refreshes the TTL and updates the mutable fields. This is how clients keep subscriptions alive. + +```jsonc +{ + "jsonrpc": "2.0", + "method": "events/subscribe", + "id": 2, + "params": { + "name": "incident.created", + "arguments": { "severity": "P1" }, + "delivery": { + "mode": "webhook", + "url": "https://proxy.example.com/hooks/client123", + "secret": "whsec_", + }, + "cursor": null, + "maxAgeMs": 300000, + "ttlMs": 3600000, // suggested TTL; omit = server default, null = request no expiry (see Subscription TTL) + }, +} +``` + +```jsonc +// Response +{ + "resultType": "complete", + "id": "sub_a3f1c8e2b0d49f7e", // server-derived; stable for this (principal, url, name, arguments) + "refreshBefore": "2026-02-19T16:30:00Z", // authoritative grant; SHOULD be ≤ the suggested ttlMs; null = no expiry + "cursor": "cursor_start_001", // safe-to-persist watermark; advances the client's cursor even if no events arrive before the next refresh + "truncated": false, // true if delivery started later than the supplied cursor +} +``` + +- `events/subscribe` is used only for webhook delivery. Poll and push do not need it. +- `delivery.secret` is REQUIRED. The client supplies the HMAC signing secret, and the server never generates one. The value MUST be a Standard Webhooks symmetric secret: the literal prefix `whsec_` followed by the base64 encoding of 24 to 64 random bytes. Servers MUST reject other values with `InvalidParams`. Client SDKs SHOULD generate the secret for the application, and SHOULD NOT expose an interface that encourages hand-picked values. +- `id` (response only) is a server-derived handle for the subscription, deterministic over `(principal, delivery.url, name, arguments)`. The server returns it so that the receiver can route deliveries: it appears in the `X-MCP-Subscription-Id` header on every POST. It is stable across refreshes and server restarts. The client does not generate or send it. +- `cursor` (request) tells the server where to begin delivery. `null` means "start from now". A non-null value requests replay from that position, and is honored when the event type is backed by a durable upstream. The cursor is owned by the client. The server does not persist a cursor position per subscription across restarts. It computes a safe-to-persist watermark, includes it in each delivered payload (see [Webhook event delivery](#webhook-event-delivery)), and returns the same watermark in each subscribe or refresh response, so the client's cursor advances during quiet periods. Both sources carry the same semantics, so the client persists whichever it received most recently and supplies it on every refresh. If the subscription is live, the supplied cursor is at or behind the server's in-flight position, and the server treats it as a no-op: delivery continues uninterrupted. If the subscription has lapsed or the server has restarted, the cursor becomes the replay point. Clients therefore follow a single rule, which is to always pass the last persisted cursor, and the server is idempotent under it. +- `cursor` (response) is the same safe-to-persist watermark that the server includes in delivery payloads: a position at or before which everything has been acknowledged or abandoned. Returning it here lets the client's cursor advance during quiet periods when no event POSTs arrive. Without it, a long quiet stretch could leave the client holding a cursor older than the upstream's retention window. When deliveries are in flight, the response cursor is at or behind the upstream head and does not advance past unacknowledged events, so persisting it never skips anything. It is `null` for event types that do not support replay. +- `ttlMs` (request, optional) is the client's suggested lifetime. `refreshBefore` (response, always present, nullable) is the server's authoritative grant: an ISO 8601 timestamp for when the subscription expires, or `null` for no expiry. Unless it was granted no expiry, the client MUST call `events/subscribe` again with the same subscription key before `refreshBefore` to keep the subscription alive. The server grants a TTL again on each refresh. See [Subscription TTL](#subscription-ttl). +- `events/subscribe` is idempotent within the caller's subscription scope. If a subscription with the same scoped key exists, the server resets the TTL and updates the mutable fields in place. If the subscription has expired, or the server has restarted and lost it, the server creates a fresh subscription using the supplied cursor. +- The server holds subscription state (event name, arguments, callback URL, secret, derived `id`) with a TTL per subscription. How durably it holds that state is its own choice, coupled to the TTLs it grants. A server that grants short TTLs can keep everything in memory. If it restarts, clients resubscribe on their next refresh cycle. For event types backed by a durable upstream, the client's persisted cursor recovers events that occurred during the gap. Emit-only event types lose them (see [Appendix A](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/3415-events-extension.md#appendix-a-sdk-guidance-non-normative)). A server that grants long or no-expiry TTLs MUST retain subscriptions for the lifetime it granted, including across restarts. + +#### Subscription TTL + +Every webhook subscription has a lifetime negotiated at subscribe time. The client suggests, the server decides, and the server's answer is authoritative. + +- `ttlMs` (request, optional, nullable integer) is the client's suggested lifetime in milliseconds. The client knows best how long it is likely to be around. A short-lived session should suggest minutes. A long-lived tenant that holds many subscriptions can suggest days or more, so that it is not forced to refresh on a cadence the server invented. Omitting the field means "server default". An explicit `ttlMs: null` requests a subscription with **no expiry**. +- `refreshBefore` (response) is the grant. It SHOULD be less than or equal to the suggestion. The client asked for what it can commit to refreshing, and a longer grant risks the server delivering to an endpoint past the client's expected lifetime. The one sanctioned exception is a server-side floor: a server MAY clamp an impractically short suggestion up to its minimum TTL, to protect itself from refresh storms. Clamping in either direction announces itself. The client reads the granted `refreshBefore` and schedules its refresh loop from that, so a clamped grant is not an error, and there is no rejection path for TTL values. +- `refreshBefore: null` grants **no expiry**. The subscription persists until `events/unsubscribe` or server-initiated termination. A server MUST NOT return `null` unless the client suggested `ttlMs: null`, because no expiry exceeds every finite suggestion. A server that is unwilling to grant it returns a finite `refreshBefore`, which the client treats like any other grant. + +**Recommended grants.** For finite TTLs, grants from a few minutes up to about a day cover most deployments. The trade-off is asymmetric. The cost of a short TTL is refresh traffic, which scales as O(1/TTL) and is negligible at any reasonable value. The clamp-up floor above exists to exclude unreasonable ones. The cost of a long TTL is subscription storage and slower reclamation of abandoned subscriptions, which scales as O(TTL). Refreshing once a day is not a meaningful burden on clients. Beyond a day, the marginal saving in refresh traffic is close to zero while the retention burden keeps growing. A subscription that needs to outlive that is better modelled as an explicit no-expiry request (`ttlMs: null`, with the obligations below) than as a very long finite TTL. This is guidance about sensible defaults and not a ceiling: a client may still suggest more, and a server MAY honor it. Servers that expect only short-lived subscribers, such as a coding agent following a single CI run, can reasonably cap grants at minutes to an hour. + +**TTL is the server's resource-control knob.** A server that wants refresh-driven cleanup and in-memory soft state grants short TTLs. A server that grants long TTLs is choosing to hold subscription state for that long, and should hold it durably enough to honor the grant. There is no sharp boundary to defend. A one-year TTL is unlimited in every practical sense, and excluding `null` from the protocol would only invite "999 years". Offering no expiry explicitly lets this specification attach the real obligations to it. A server that grants no expiry accepts that: + +- The client is not expected to refresh or unsubscribe, ever. Keeping the subscription alive is now the server's job. +- Restart recovery through the refresh cycle no longer applies. The server MUST persist no-expiry subscriptions across restarts, because a client that never refreshes will never detect or repair one that was silently dropped. +- TTL expiry no longer collects orphans or dead endpoints. The server MAY drop a no-expiry subscription after sustained delivery failure over a server-defined window, and SHOULD attempt a `terminated` envelope when it does. + +Even with no expiry, clients SHOULD still call `events/subscribe` and `events/list` occasionally. The refresh response is where the cursor advances during quiet periods, where `deliveryStatus` surfaces delivery problems, and where suspended delivery reactivates (see [Webhook event delivery](#webhook-event-delivery)). A periodic `events/list` bounds how long a descriptor change can go unnoticed by a client with no live connection. The difference is that correctness no longer depends on these calls. + +#### Subscription identity + +Webhook subscriptions are keyed by a compound **subscription key**, which determines which `events/subscribe` calls refer to the same logical subscription. The server uses the key for idempotent upsert on subscribe, for lookup on unsubscribe, and to isolate tenants from one another. + +**Authentication required.** `events/subscribe` and `events/unsubscribe` MUST be called with an authenticated principal. Servers MUST reject calls without an authorized principal with `Forbidden`. Without a principal in the key, the tuple `(delivery.url, name, arguments)` is guessable, and any caller could unsubscribe another tenant or rotate its secret. Unauthenticated MCP servers may offer poll and push, but not webhook. + +**Key composition.** The subscription key is `(principal, delivery.url, name, arguments)`. `principal` is the server's canonical identifier for the authenticated subject, such as an OAuth `sub`, an API key ID or a service-account name. `arguments` is compared by canonical-JSON equality. There is no client-generated `id`: a subscription is fully determined by what it listens for, where it delivers and who asked. + +All four components are immutable for the subscription's lifetime. A subscribe call with a different value for any of them addresses a different subscription. To change what a subscription listens for or where it delivers, the client calls `events/unsubscribe` for the old one and `events/subscribe` for a new one. This avoids the case where `name` or `arguments` change in place but an upstream listener that the server provisioned stays bound to the old values. + +**Derived `id`.** The server computes a deterministic `id` over the key, for example a truncated SHA-256 of the canonical key serialization, and returns it in the subscribe response. It is a routing handle and not a capability. It appears in `X-MCP-Subscription-Id` on every delivery and MAY be logged. Knowing it does not authorize anything. + +On an idempotent subscribe against an existing key, the server updates the remaining fields as follows: + +| Field | Behavior on an existing subscription | +| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `delivery.secret` | Replaced. To rotate, the client supplies a new value on refresh. The server SHOULD dual-sign (Standard Webhooks multi-signature) with the old and new secrets for a short grace window, so that in-flight deliveries verify under either. | +| `cursor` | The server treats the supplied value as the client's last persisted position. If the subscription is live and the cursor is at or behind the current in-flight position, this is a no-op. If the subscription has lapsed or the server restarted, delivery starts or restarts from this position. The server does not store the value beyond initiating delivery. | +| TTL | Granted again. The refresh carries a `ttlMs` suggestion, which may differ, and the server returns a fresh `refreshBefore` under the same rules as the initial subscribe. A client can therefore lengthen or shorten its refresh cadence, or convert a no-expiry subscription back to a finite one by suggesting a finite `ttlMs`. | +| `active` | Set to `true`. A successful refresh is the client's liveness signal. If delivery had been suspended (`active: false` in `deliveryStatus`) because of repeated failures, the server resumes retrying pending events. | + +**Cross-tenant isolation.** Because the key includes `principal` and `delivery.url`, two tenants that subscribe to the same `(name, arguments)` get distinct subscriptions. A caller who learns another tenant's derived `id` gains nothing, because `id` is not accepted as input to any method. + +#### Webhook event delivery + +The server POSTs events to the callback URL as they occur: + +``` +POST https://proxy.example.com/hooks/client123 +Content-Type: application/json +webhook-id: msg_2KWPBgLlAfxdpx2AI54pPJ85f4W +webhook-timestamp: 1739980800 +webhook-signature: v1, +X-MCP-Subscription-Id: sub_a3f1c8e2b0d49f7e + +{ + "eventId": "evt_789", + "name": "incident.created", + "timestamp": "2026-02-19T16:00:00Z", + "data": { + "incidentId": "INC-1234", + "title": "Database connection pool exhausted", + "severity": "P1" + }, + "cursor": "cursor_xyz" +} +``` + +- **Headers.** Deliveries follow the [Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md) signature scheme (see [Signature scheme](#webhook-security)). `X-MCP-Subscription-Id` is an MCP-specific header that carries the subscription `id`, so that the receiver can select the correct secret before it parses the body. The receiver MUST verify the signature before processing, SHOULD reject deliveries whose `webhook-timestamp` is more than 5 minutes old, and SHOULD deduplicate on `webhook-id`, which identifies the delivered message and not the event. Each retry attempt keeps the `webhook-id` and regenerates the timestamp and signature. +- **`eventId`** in the body identifies the upstream event. A receiver that deduplicates by it MUST scope that to the subscription (`X-MCP-Subscription-Id`): the same `eventId` delivered on two subscriptions is two deliveries, and both are processed. +- **`cursor`** in the body is a **safe-to-persist watermark**: a position such that every event at or before it has been acknowledged by the endpoint or abandoned by the server. The server computes it from its in-memory retry queue. It does not include `cursor_N` in event N's payload until the events at positions before N have been acknowledged or given up on. Computing this requires the server to hold, per active subscription, the upstream position and acknowledgement status of in-flight events. This is in-memory, TTL-scoped state that is lost on restart and rebuilt by a client refresh, but it is bookkeeping per subscription that a server SDK has to implement. The client persists every cursor it receives, and the most recently received value is always safe to supply on refresh. The server MAY send `cursor: null` for event types that do not support replay, in which case there is no recovery point to persist. The endpoint MUST make `cursor` and `eventId` available to the consuming client by whatever channel it uses to forward events, because cursor-based recovery on resubscribe depends on the client receiving and persisting the value. +- **Delivery model.** The server retries each event independently, with exponential backoff, on non-`2xx` responses. This matches the dominant webhook convention (Stripe, GitHub, Shopify, the Standard Webhooks specification). Concurrent deliveries and retries may therefore arrive out of order. The receiver uses `webhook-id` to discard retried deliveries, and `timestamp` for ordering if it needs it. Because the payload `cursor` is a watermark and not the event's own position, out-of-order arrival does not cause the client to persist an unsafe cursor. Retries are bounded. Servers SHOULD cap both the attempt count and the elapsed retry window, for example 3 to 5 attempts spread over no more than 10 to 15 minutes, and SHOULD NOT retry indefinitely. Time spent with delivery suspended (see below) pauses the window and does not consume it. An event whose retries are exhausted is abandoned for watermark purposes and, where the upstream is durable, can be recovered by cursor replay. A receiver that intentionally rejects a delivery and does not want it retried, for example because it recognizes the event as stale or already processed, responds `410 Gone`. The server MUST treat `410` as a non-retryable failure for that delivery (like `413`, see [Delivery profile](#webhook-security)), without affecting the subscription itself. +- **Acknowledgement semantics.** A `2xx` response from the webhook endpoint signals that the event has been accepted and the server need not retry it. The endpoint SHOULD NOT return `2xx` until the event has been durably persisted or forwarded. An endpoint that acknowledges an event and then loses it leaves recovery dependent on the client's last persisted cursor, which may predate the lost event. At-least-once delivery in webhook mode holds between server and endpoint. End-to-end delivery to the agent depends on the endpoint honoring this contract. How long the server waits for the response before it treats the attempt as failed (`lastError: "timeout"`) and retries is a server implementation detail and not a protocol parameter. A timeout on the order of 5 seconds is common. Endpoints SHOULD therefore respond quickly: durably accept the event by persisting or enqueueing it, return `2xx`, and do heavier processing asynchronously. +- **Subscribe and delivery race.** Because the secret is supplied by the client, the receiver can verify the very first delivery. There is no window in which a delivery arrives before the receiver knows the secret. A receiver that gets a delivery for an `id` it has not yet been told to route, for example because the subscribe response has not propagated to the gateway, SHOULD return a retryable status (`503` or `425 Too Early`). The server's retry and backoff redelivers once the receiver is ready. `webhook-id` deduplication and cursor replay make this safe. This guidance covers event deliveries and the `gap` and `terminated` envelopes. It does not cover a `verification` envelope, which on a first subscribe always arrives before the receiver has been given the `id` (see [Endpoint verification](#webhook-security)). +- **Suspension.** After repeated failures, at a server-defined threshold, the server MAY suspend delivery (`deliveryStatus.active: false`). As implementation guidance, base suspension on a sustained failure rate over a meaningful sample and not on a fixed failure count. An example is a delivery failure rate above 95% over a rolling 60-minute window with a minimum of 100 delivery attempts. A brief endpoint blip then does not suspend a healthy subscription, and a low-traffic subscription is not suspended on a handful of failures. A later successful refresh reactivates the subscription (sets `active: true`), and the server resumes retrying pending events. If the client never refreshes, the subscription expires at its TTL. A no-expiry subscription has no such backstop: the server MAY drop it after sustained delivery failure, and SHOULD attempt a `terminated` envelope when it does (see [Subscription TTL](#subscription-ttl)). + +#### Non-event webhook bodies + +In addition to `EventOccurrence` bodies, the server POSTs control envelopes to the callback URL. A body with a top-level `type` field is a control envelope, and a body without one is an `EventOccurrence`. Control envelopes are signed and carry the same headers as event deliveries (the Standard Webhooks headers and `X-MCP-Subscription-Id`). The body carries a `type` discriminator in place of `eventId` and `data`. `webhook-id` for a control envelope is a per-message identifier of the form `msg__`, so that receivers can deduplicate retries. The endpoint MUST forward `gap` and `terminated` envelopes to the consuming client by the same channel it uses to forward events. A `verification` envelope is consumed by the endpoint itself, which answers it in the HTTP response, and is not forwarded. The client learns the outcome from the `events/subscribe` result. + +| `type` | Body | Sent when | +| -------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `gap` | `{"type":"gap","cursor":""}` | A gap is detected between refreshes (see [Cursor Lifecycle](#cursor-lifecycle)). The client persists `cursor` and treats it as `truncated: true`. | +| `terminated` | `{"type":"terminated","error":{"code":...,"message":...,"data":...}}` | The subscription has ended, for example because authorization was revoked. The subscription no longer exists on the server. | +| `verification` | `{"type":"verification","challenge":""}` | Sent before the server activates delivery to an unverified `(principal, url)` (see [Endpoint verification](#webhook-security)). The endpoint echoes `challenge` in a `2xx` body to prove intent. The server activates delivery only on a constant-time match. | + +#### Webhook delivery status + +The `events/subscribe` response MAY include a `deliveryStatus` object when it refreshes an existing subscription. This lets the client detect delivery problems without a separate monitoring channel. + +```jsonc +// Healthy subscription refresh +{ + "resultType": "complete", + "id": "sub_a3f1c8e2b0d49f7e", + "refreshBefore": "2026-02-19T17:00:00Z", + "cursor": "cursor_xyz", + "truncated": false, + "deliveryStatus": { + "active": true, + "lastDeliveryAt": "2026-02-19T16:28:00Z", + "lastError": null, + }, +} +``` + +```jsonc +// Subscription with delivery failures +{ + "resultType": "complete", + "id": "sub_a3f1c8e2b0d49f7e", + "refreshBefore": "2026-02-19T17:00:00Z", + "cursor": "cursor_xyz", + "truncated": false, + "deliveryStatus": { + "active": false, + "lastDeliveryAt": "2026-02-19T15:45:00Z", + "lastError": "http_4xx", + "failedSince": "2026-02-19T15:50:00Z", + }, +} +``` + +```jsonc +// Subscription being actively rate-limited (deliveries delayed, not failing) +{ + "resultType": "complete", + "id": "sub_a3f1c8e2b0d49f7e", + "refreshBefore": "2026-02-19T17:00:00Z", + "cursor": "cursor_xyz", + "truncated": false, + "deliveryStatus": { + "active": true, + "lastDeliveryAt": "2026-02-19T16:28:00Z", + "lastError": null, + "throttled": true, + "retryAfterMs": 60000, + }, +} +``` + +`deliveryStatus` is OPTIONAL, and servers MAY omit it entirely. When it is present: + +- `active` says whether the server is currently delivering events. `false` means it has suspended retries after repeated failures, and the refresh that returned this status has just reactivated it. +- `lastError` MUST be a server-generated category string, one of `connection_refused`, `timeout`, `tls_error`, `http_4xx`, `http_5xx` or `challenge_failed`. It MUST NOT include raw response bodies, headers or status lines from the endpoint, so that it cannot serve as a response oracle for attacker-chosen URLs. The client can use it to diagnose connectivity or authentication problems with the webhook endpoint. The same categories appear as `data.reason` on a `CallbackEndpointError` returned synchronously from `events/subscribe`. +- `throttled` (optional boolean) distinguishes active rate-limiting from failure-driven suspension. `true` means the server is currently limiting outbound deliveries for this subscription. Deliveries are being delayed and are not failing, so the client should not read reduced traffic as "nothing is happening" or as an endpoint problem. +- `retryAfterMs` (optional integer) accompanies `throttled` as a hint for how long the client should expect throttling to last before normal delivery resumes. + +`throttled` and `retryAfterMs` are advisory, and servers that do not rate-limit outbound deliveries never send them. A server whose protective throttling goes further and skips events outright signals that as a gap (a `gap` envelope or `truncated: true`), and not through these fields. + +#### Webhook security + +**SSRF prevention.** The server MUST validate callback URLs. Servers SHOULD reject URLs whose resolved IP is not globally routable per the [IANA IPv4](https://www.iana.org/assignments/iana-ipv4-special-registry/) and [IPv6](https://www.iana.org/assignments/iana-ipv6-special-registry/) Special-Purpose Address Registries, unless they are explicitly configured to allow them. Illustrative examples are `127.0.0.0/8`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `169.254.0.0/16`, `::1`, `fc00::/7` and `fe80::/10`. To prevent DNS rebinding, this validation MUST be performed at delivery time, and not only at subscribe time. The server resolves the hostname, checks the resolved IP against the blocklist, and connects directly to that validated IP, sending the original hostname in the `Host` header and TLS SNI, so that the address cannot change between the check and the connection. Validation at subscribe time alone is insufficient, because a rebinding attacker returns a public IP at subscribe time and a private IP at delivery time. Webhook delivery requests MUST NOT follow HTTP redirects, because a redirect can target an internal address that bypasses the blocklist. Servers MAY additionally maintain an allowlist of permitted callback URL patterns. + +**Endpoint verification (anti-flooding).** A client-supplied HMAC secret stops a third party from being _deceived_, because forged deliveries fail verification. It does not stop a third party from being _flooded_: an attacker can subscribe a victim's URL with an attacker-chosen secret, and the victim still receives every POST. A server therefore MUST NOT begin delivering to a callback URL until the endpoint's intent to receive deliveries is confirmed, by **one of**: + +1. A **verification handshake**. Before activating, the server POSTs a `verification` control envelope that carries a single-use, short-lived `challenge` nonce, signed and headed like any delivery. The endpoint proves intent by echoing the nonce in a `2xx` body (`{"challenge":""}`), which the server compares in constant time. +2. The URL matching a server-configured **allowlist**. +3. Prior **out-of-band verification** of the URL by the server through its own mechanism, for example registration and confirmation in the server's dashboard. +4. A **receiver-published well-known document**. The callback URL's `https` origin serves `/.well-known/mcp-webhook-receiver.json`, which declares the path prefixes under that origin that accept MCP webhook deliveries (for example `{"receivers": ["/hooks/"]}`). A callback URL covered by it is verified, with control of the origin standing in as the proof of intent. The server fetches the document over the same SSRF-hardened path it uses for deliveries, and MAY cache it per origin for a bounded period, respecting HTTP caching headers. The verification it establishes is still recorded per `(principal, url)` like the other paths. The difference is that no challenge POST is needed, because the origin has already published its consent. This is a standing, self-serve allowlist for receivers that can publish same-origin static content, typically a gateway or integration platform that fronts many subscriptions. Receivers whose delivery origin is not something they can publish documents on use options 1 to 3. + +A reachable endpoint that fails to echo the challenge yields `CallbackEndpointError` with `data.reason: "challenge_failed"`. An unreachable one yields the same error with the relevant connection-failure category (`connection_refused`, `timeout` or `tls_error`). + +On a first subscribe the server sends the challenge while it is still processing `events/subscribe`, so the `X-MCP-Subscription-Id` header on it carries an `id` that the receiver has not yet been given. The receiver cannot select the secret by `id` in this case. It instead checks the signature against the secrets that have been registered with it and are not yet associated with an `id`. As with any delivery, the receiver verifies the signature before it acts, so it echoes the nonce only if one of those secrets verifies. It MAY record the `id` from the header against that secret at that point, without waiting for the subscribe response to reach it. The retryable-status guidance in [Webhook event delivery](#webhook-event-delivery) does not apply here. The challenge is answered within the `events/subscribe` call, and a non-`2xx` response fails that call with `CallbackEndpointError`. + +Verification is cached per `(principal, url)`. A successful handshake, allowlist hit or well-known match covers that principal's subscriptions to that URL across refreshes and `arguments`. Varying `arguments` therefore cannot multiply verification POSTs at a victim, and one principal's verification never waives the challenge for another. The cache is in-memory, TTL-scoped soft state like the subscription itself, and after a restart the server verifies again on the next subscribe. A server that persists no-expiry subscriptions across restarts MUST persist their verification status alongside them. A persisted subscription resumes delivery without a resubscribe, so there is no later handshake to lean on, and the stored record exists only because verification succeeded. The verification POST MUST use the same SSRF-hardened path as deliveries (delivery-time IP validation, no redirects) and SHOULD be rate-limited per destination host. Failures surface only through the `lastError` category `challenge_failed`, and never through raw endpoint responses. + +**Server identity (optional).** A server MAY additionally sign deliveries and verification POSTs with an asymmetric key (Standard Webhooks `v1a,`, ed25519), appended alongside the `v1,` HMAC. A gateway can then verify _which_ server sent a delivery, enforce an allowlist of known servers, and keep protection if an HMAC secret leaks. The verifying public key MUST be discovered from an origin the client already authenticates, and never from the challenge or delivery body, which the attacker controls and which would make this trust-on-first-use. The key is published on the server's Server Card, in the `signingKeys` member of `remotes[].extensionsInfo["io.modelcontextprotocol/events"].webhooks` on the remote entry for the MCP endpoint, as a JWK set of ed25519 keys (`kty: "OKP"`, `crv: "Ed25519"`). The gateway fetches the card from the same origin it connects to for MCP. The gateway MUST NOT use keys from a card hosted on another origin or reached through a cross-origin redirect, as the Server Card specification requires for security-relevant extension information. This location depends on [ext-server-card#55](https://github.com/modelcontextprotocol/ext-server-card/pull/55), which adds the `extensionsInfo` map to Server Card remotes. It is distinct from the OAuth `jwks_uri` ([RFC 8414](https://www.rfc-editor.org/rfc/rfc8414)), which carries the authorization server's token-signing keys and not the MCP server's webhook-signing key. Keys carry a `kid`, and rotation publishes the new key alongside the old. Endpoints that do not enforce server identity ignore `v1a,`. + +**TLS requirement.** Callback URLs MUST use `https://`. Servers MUST reject `events/subscribe` with a non-`https` `delivery.url` (`InvalidParams`). Event payloads, and the `delivery.secret` sent in the subscribe request, would otherwise transit in cleartext. + +**Signature scheme (Standard Webhooks profile).** MCP webhook delivery is a profile of [Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md). + +- Every delivery MUST include `webhook-id`, `webhook-timestamp` and `webhook-signature`. `webhook-id` identifies the delivered message. The server generates it: it is high-entropy, unique per message (one event on one subscription, or one control envelope), reused across retries of that message, and consists only of ASCII letters, digits, `_` and `-`. It MUST NOT be derived from `eventId`, which comes from the upstream, may not be header-safe, and is shared by every subscription the event matches. Control envelopes use the form `msg__`. `webhook-timestamp` is the Unix timestamp of the request in seconds. +- The signature is `HMAC-SHA256(secret, webhook-id + "." + webhook-timestamp + "." + body)`, encoded as base64 with a `v1,` prefix. `body` is the raw HTTP request body bytes exactly as received, before any parsing or re-serialization. The `webhook-id + "." + webhook-timestamp + "."` prefix is UTF-8. `secret` is the base64-decoded bytes of the value after the `whsec_` prefix. +- Receivers MUST compute the HMAC over the raw body, and never over a re-serialized JSON object. +- The header MAY contain several space-delimited signatures (`v1, v1,`) during secret rotation. The receiver accepts the delivery if any of them verifies. +- Each retry attempt MUST regenerate the timestamp and signature, so that retries are not rejected by the receiver's freshness window. The receiver SHOULD reject deliveries whose `webhook-timestamp` is more than 5 minutes old. +- Deliveries MUST also include `X-MCP-Subscription-Id` (the subscription `id`), so that the receiver can select the correct secret without parsing the body. This is the only MCP-specific header. Everything else conforms to Standard Webhooks, and off-the-shelf Standard Webhooks verifiers work without modification. + +**Secret generation.** The signing secret is supplied by the client in `delivery.secret` and is REQUIRED. The server never generates one. This places the secret with the party that verifies deliveries (the gateway or receiver). The receiver is ready to verify the first POST without any coordination after the subscribe, and a subscription pointed at an endpoint that did not originate the secret fails verification by construction. Servers MUST reject a `delivery.secret` that is not `whsec_` followed by base64 that decodes to 24 to 64 bytes. Client SDKs SHOULD generate it from a CSPRNG by default. + +**Secret rotation.** The client supplies a new `delivery.secret` on a refresh call, and the idempotent upsert replaces it. The server SHOULD dual-sign deliveries with both the old and new secrets for a short grace window, so that in-flight deliveries verify under either. There is no server-initiated rotation. + +**Authentication to the callback endpoint.** HMAC is the only authentication mechanism this extension defines between the MCP server and the callback endpoint. This matches the dominant pattern for product webhooks (Stripe, GitHub, Slack and Twilio all authenticate deliveries with HMAC alone), and keeps the server's credential surface per subscription to a single secret. + +HMAC is verified by application code after the request has been routed. It does not help if the callback URL sits behind infrastructure that requires transport-level authentication before routing, such as an API gateway that demands `Authorization: Bearer`, a cloud endpoint that requires a platform-issued identity token, or an mTLS-only mesh. For those deployments, point the callback at a forward proxy under the tenant's control. The proxy presents a public endpoint to the MCP server, terminates HMAC, and re-authenticates to downstream services with whatever mechanism the internal network requires. This extension does not provide a way to pass through bearer tokens, perform an OAuth client-credentials grant, or attach OIDC identity tokens on the tenant's behalf. These may be considered for a future revision if deployment experience warrants it. + +**Delivery profile (for WAF and private-cloud deployments).** Gateways are commonly fronted by a WAF, API gateway or ingress controller that needs static rules to admit legitimate deliveries. Such infrastructure can rely on the following invariants: + +- **Method.** Deliveries are HTTP `POST` only. +- **Content-Type.** `application/json`. +- **Required headers.** `webhook-id`, `webhook-timestamp`, `webhook-signature` and `X-MCP-Subscription-Id` are present on every delivery. A WAF MAY drop requests that are missing any of them as a cheap pre-filter. HMAC remains the actual security boundary. +- **Body size.** Servers SHOULD keep delivery bodies at or under 256 KiB, consistent with [Payload minimality](#payload-minimality). Receivers and intermediaries MAY reject larger bodies with `413 Payload Too Large`. Servers MUST treat `413` as a non-retryable failure for that event. +- **TLS.** `https` is mandatory for `delivery.url`. Intermediaries MAY terminate TLS. Nothing in the verification path depends on end-to-end TLS, because the HMAC covers the raw body and timestamp. +- **User-Agent.** Not specified by this extension. A standard MCP user-agent format is under discussion in [SEP-1336](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1336). If it is adopted, webhook deliveries would follow it. WAF rules SHOULD NOT rely on user-agent matching as a security control in any case. +- **Source IP allowlisting.** This is defence in depth and not the security boundary. A server MAY publish its egress ranges on its Server Card, in the `egressIpRanges` member of `remotes[].extensionsInfo["io.modelcontextprotocol/events"].webhooks`, as an array of CIDR strings. This location depends on [ext-server-card#55](https://github.com/modelcontextprotocol/ext-server-card/pull/55). Servers that do not publish a Server Card SHOULD document their egress ranges out of band. Gateways that cannot obtain stable ranges (serverless, dynamic NAT) rely on HMAC alone, which is sufficient. + +#### Unsubscribing: `events/unsubscribe` + +`events/unsubscribe` is an eager cleanup mechanism. It is not required for correctness, because subscriptions expire when the client stops refreshing. Calling it frees server resources and stops webhook deliveries immediately, without waiting for TTL expiry. No-expiry subscriptions never lapse, so `events/unsubscribe` is the only client-initiated cleanup for them. A server that grants no expiry MUST NOT count on receiving it (see [Subscription TTL](#subscription-ttl)). + +```jsonc +{ + "jsonrpc": "2.0", + "method": "events/unsubscribe", + "id": 3, + "params": { + "name": "incident.created", + "arguments": { "severity": "P1" }, + "delivery": { "url": "https://proxy.example.com/hooks/client123" }, + }, +} +``` + +`events/unsubscribe` resolves the subscription with the same key as `events/subscribe`: `(principal, delivery.url, name, arguments)`. The client supplies `name`, `arguments` and `delivery.url`, and `principal` comes from the authorization layer. The derived `id` is not accepted as input. The result is an empty `Result`. + +`events/unsubscribe` is used only for webhook delivery. Poll subscriptions are implicit: the client stops polling to unsubscribe. Push subscriptions are scoped to the `events/stream` request: the client closes or cancels it to unsubscribe. + +### Cursor Lifecycle + +Cursors are opaque strings managed by the server. They represent a position in the event stream. + +**Replay is optional per event type.** A server MAY return `cursor: null` in any delivery (a poll result, a push `notifications/events/event` or `notifications/events/active`, a webhook payload) when the event type does not support replay. This is typically because the upstream is push-only and has no addressable history. A client that receives `cursor: null` MUST NOT attempt to persist or replay from it. On reconnect or resubscribe it sends `cursor: null` (start from now), and accepts that events during the gap cannot be recovered. Servers SHOULD be consistent: an event type that ever returns a non-null cursor SHOULD always do so, and one that returns `null` SHOULD always return `null`. Clients can then branch once at subscribe time and not on every delivery. + +**Initial cursor.** Passing `cursor: null` in any mode means "start from now". The server returns a fresh cursor for the current position, or `null` if the event type does not support replay. No historical events are replayed. + +**Absent means `null`.** `cursor` is optional and nullable everywhere it appears: in requests, responses and delivered payloads. An absent `cursor` field MUST be treated identically to an explicit `cursor: null`. A sender MAY omit the field in place of writing `null`, and a receiver MUST NOT fail because it is missing. This holds in both directions. An emit-only server with no replay history can simply never emit the field, a client with nothing persisted can omit it on subscribe or poll, and both remain conformant. + +**Cursor advancement without events.** The client's persisted cursor has to advance during quiet periods, so that it does not fall outside the upstream's retention window when nothing is happening. Poll covers this inherently, because every response carries `cursor`, including when `events` is empty. For push, the heartbeat carries `cursor`. For webhook, each `events/subscribe` refresh response carries `cursor`. In all three the value is safe to persist. For webhook it is the same watermark as in delivery payloads, and is never ahead of unacknowledged events. The client persists it exactly as it would a cursor from a delivered event. + +**Bounding replay with `maxAgeMs`.** All three modes accept an optional `maxAgeMs` (integer milliseconds) alongside `cursor`. When it is present, the server begins replay from whichever is _later_: the supplied `cursor`, or `now − maxAgeMs`. A client can therefore resubscribe with a stale cursor without receiving an unbounded backlog. For example, a host that was offline for a week can pass its persisted cursor with `maxAgeMs: 300000` and get at most the last five minutes. + +- If the floor advances past the cursor, the server SHOULD set `truncated: true` on the first response (the poll result, `notifications/events/active`, or the webhook subscribe response), so that the client knows older events were skipped. +- Servers whose upstream supports time-addressed reads (Gmail `after:`, Slack `oldest=`, Kafka `offsetsForTimes`) SHOULD seek directly. Others MAY honor `maxAgeMs` by replaying from `cursor` and discarding events whose `timestamp` is older than the floor. If that would be prohibitively expensive, such as a week-old cursor with `maxAgeMs: 300000`, they MAY instead reset to now and return `truncated: true`, which gives the same client-visible outcome without the wasted scan. +- Servers MAY also apply their own replay ceiling independent of `maxAgeMs`, and MUST signal it with `truncated: true` when they do. +- `maxAgeMs` is ignored when `cursor` is `null`, because `null` already means "now" and replay from before the subscription's start is out of scope. It is also ignored for event types that do not support replay. + +**Gaps and `truncated`.** `truncated: true` is the single signal that the server started delivery from a position later than the cursor the client supplied, which means events were skipped. Causes are not distinguished on the wire. The supplied cursor may have fallen outside the upstream's retention window, the `maxAgeMs` floor may have advanced past it, or the server may have applied its own replay ceiling. In every case the server resets to a position it can serve from, returns that position as the fresh `cursor` alongside `truncated: true`, and continues. The client never reconnects or resubscribes in response. `truncated: true` always implies a possible gap. Clients SHOULD treat it as one, for example by fetching authoritative state again with tools if it matters, and SHOULD persist the fresh cursor. + +| Mode | Where `truncated` appears | +| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Poll | The result body: `{events:[], cursor:, truncated:true, hasMore, nextPollMs}`. Never a JSON-RPC error. | +| Push | A `notifications/events/active {cursor:, truncated:true, _meta.subscriptionId}` is sent, initially and again mid-stream if a gap occurs. Delivery continues on the same stream. | +| Webhook | The subscribe or refresh response: `{id, refreshBefore, cursor:, truncated:true, ...}`. For a gap detected between refreshes, the server POSTs a `{"type":"gap","cursor":""}` control envelope, so that the client learns of it without waiting for the next refresh. | + +For event types that do not support replay, where `cursor` is always `null`, `truncated` SHOULD be `false` and clients SHOULD ignore it. There is no position to have advanced past. + +### Subscription Termination + +A server ends a subscription when the principal's access is revoked (see [Authorization](#authorization)), or when the event type is removed or changed incompatibly (see [Event type removal and breaking changes](#event-type-removal-and-breaking-changes)). The termination signal carries the same nested `error` shape in every mode: + +| Mode | Transport | +| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Push | `notifications/events/terminated` on the stream. | +| Poll | A JSON-RPC error response to the next `events/poll` request. | +| Webhook | A signed `{"type":"terminated",...}` envelope POSTed to the callback URL. The subscription no longer exists, so a later refresh is a fresh subscribe, and returns `Forbidden` if the cause of termination still applies. | + +```jsonc +// Push +{"jsonrpc":"2.0","method":"notifications/events/terminated","params":{"error":{"code":-32024,"message":"Forbidden","data":{"reason":"Access revoked"}},"_meta":{"io.modelcontextprotocol/subscriptionId":1}}} + +// Webhook (POST body) +{"type":"terminated","error":{"code":-32024,"message":"Forbidden","data":{"reason":"Access revoked"}}} +``` + +`notifications/events/terminated` has the shape `{error: {code: integer, message: string, data?: object}, _meta: {"io.modelcontextprotocol/subscriptionId": string | integer}}`. It is identical to `notifications/events/error`, but indicates that the subscription has ended and not that a single event failed. The client SDK SHOULD remove the subscription and notify the application. + +### Ordering and Delivery Guarantees + +This extension does not provide protocol-level guarantees of event ordering, exactly-once delivery or transactional consistency. There are no logical clocks, sequence numbers or ordering constraints across subscriptions. What it provides is: + +- **Cursors** for resumability. The client can pick up where it left off after a disconnect or a crash. +- **`eventId`** for client-side deduplication within a subscription. The client can detect and discard duplicates that arise during reconnection. +- **Ordering per subscription.** For poll and push, events within a single subscription are delivered in the order the server produces them. For webhook, delivery order is best-effort: each event is retried independently, so concurrent requests and retries can reorder arrivals. The safe-watermark cursor in each payload makes the cursor safe to persist regardless of arrival order. Clients that need ordering use the `timestamp` field. No ordering is guaranteed across subscriptions in any mode. +- **At-least-once delivery** in all three modes when the cursor is backed by a durable upstream and the client replays from its last known cursor on reconnect or restart. Emit-only event types are at-most-once across server restarts, because the in-memory buffer and its cursors do not survive. Exactly-once requires application-level deduplication by `eventId`. + +Servers that need stronger guarantees can implement them, because the cursor is opaque and can encode whatever the server needs (see [Rationale](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/3415-events-extension.md#rationale)). Clients and agents should be designed to tolerate out-of-order and duplicate events. Agents that need stronger guarantees should use tools to read authoritative state, and should not rely solely on event payloads. + +### Client-Owned Subscription State + +The client owns all subscription state, in all three delivery modes. There is no method that lists subscriptions on the server. The client maintains its own subscription registry, and can rebuild server-side state at any time through idempotent `events/subscribe` (webhook) or by resuming poll or push with its stored cursors. + +For webhook mode, orphaned subscriptions, such as those of a crashed client, are cleaned up by TTL expiry, so no server-side listing is needed. No-expiry subscriptions are the exception. Their cleanup is the granting server's responsibility (failure-based collection, see [Webhook event delivery](#webhook-event-delivery)), which is part of what a server accepts by granting them. + +### Streamable HTTP: Routing Headers + +When `events/poll`, `events/stream`, `events/subscribe` or `events/unsubscribe` is sent over the Streamable HTTP transport, the client MUST set the `Mcp-Name` header (defined by [SEP-2243](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/2243-http-standardization.md)) to the value of `params.name`, which is the event name. This is the same source field the core protocol uses for `tools/call` and `prompts/get`. It lets transport intermediaries and load balancers route and rate-limit by event type without parsing the request body. + +The encoding and validation rules of the Streamable HTTP transport apply unchanged: + +- An event name that cannot be safely represented as a plain ASCII header value MUST be carried in the Base64 sentinel format. +- Servers validate the header as the transport's server validation rules describe. A request whose `Mcp-Name` header is missing, or does not match `params.name`, is rejected with HTTP status `400 Bad Request` and `HeaderMismatch` (`-32020`). + +`events/list` has no `params.name` and carries no `Mcp-Name` header. The `Mcp-Method` header is set to the JSON-RPC method name, as for every request. + +#### Custom headers from subscription arguments + +A server MAY mark properties in an event type's `inputSchema` with the `x-mcp-header` annotation that the Streamable HTTP transport defines for tool parameters ([Custom Headers from Tool Parameters](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http#custom-headers-from-tool-parameters)). It lets intermediaries route and apply policy on subscription arguments, such as a region or a tenant, without parsing the request body. + +```jsonc +// In the event type's descriptor +"inputSchema": { + "type": "object", + "properties": { + "region": { "type": "string", "x-mcp-header": "Region" }, + "severity": { "type": "string" } + } +} +``` + +```http +POST /mcp HTTP/1.1 +Mcp-Method: events/poll +Mcp-Name: incident.created +Mcp-Param-Region: us-west1 +``` + +The transport's rules for tools apply unchanged, with the event type in place of the tool definition, `events/list` in place of `tools/list`, and the requests below in place of `tools/call`: + +- Clients that use the Streamable HTTP transport MUST support the annotation. When `events/poll`, `events/stream`, `events/subscribe` (including each refresh) or `events/unsubscribe` is sent over that transport, the client MUST set an `Mcp-Param-{Name}` header for each annotated property that has a value in `params.arguments`, encoded as the transport describes. +- The constraints on `x-mcp-header` values are those of the transport. A client MUST exclude an event type whose annotations violate them from the result of `events/list`, and SHOULD log a warning. +- Servers validate the headers against the request body as the transport's server validation rules describe, and reject a mismatch with HTTP status `400 Bad Request` and `HeaderMismatch` (`-32020`). A client that receives this error SHOULD call `events/list` again and retry with the headers the current `inputSchema` calls for. +- Clients on other transports MAY ignore the annotation. + +Webhook deliveries are not MCP requests and carry no `Mcp-Param-*` headers. Header values are visible to network intermediaries, so servers SHOULD NOT annotate arguments that may hold sensitive data, such as a filter on a sender address. + +### Error Handling + +| Name | Code | Meaning | +| ----------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `InvalidParams` | `-32602` | The request is statically invalid: the arguments do not match the event's `inputSchema`, the callback `delivery.url` is malformed or not `https`, or `delivery.secret` is not a valid `whsec_` value. This is the standard JSON-RPC code. | +| `NotFound` | `-32023` | A referenced entity does not exist: an unknown event name, or no subscription that matches the key on `events/unsubscribe`. The method implies which. `data.kind` (`"event"` \| `"subscription"`) MAY disambiguate. | +| `Forbidden` | `-32024` | The authenticated principal is not permitted for this combination of event and arguments, or its access was revoked. | +| `ResourceExhausted` | `-32025` | A server-imposed limit or quota was reached. `data.limit` names it (for example `"subscriptions"`), and `data.max` MAY give the ceiling. | +| `Unsupported` | `-32026` | The request is well-formed, but a requested capability or option is not supported here, for example a delivery mode that the event type does not offer. `data` identifies it (for example `{ "feature": "deliveryMode", "value": "push" }`). | +| `CallbackEndpointError` | `-32027` | A client-supplied callback endpoint failed verification or could not be reached (webhook mode only). `data.reason` is one of the `lastError` categories (`connection_refused`, `timeout`, `tls_error`, `http_4xx`, `http_5xx`, `challenge_failed`). | + +The five new codes are **general-purpose**. They are named for reuse across MCP and are not scoped to events. Each conveys its specifics through a typed `data` payload, the same pattern as `UnsupportedProtocolVersionError.data`. One code therefore spans a family of conditions without minting new numbers, and clients can still distinguish every case they branch on, by code, by method or by a typed `data` discriminator. + +**Code allocation.** The core specification partitions the JSON-RPC implementation-defined range: `-32000` to `-32019` is left to implementations and is never defined by the specification, and `-32020` to `-32099` is allocated sequentially by the specification. This extension uses the next five codes in the allocated range. The numbers above assume that `-32020` to `-32022` were the only codes allocated when SEP-3415 was accepted. The codes are recorded in the core schema with the others, and future SEPs SHOULD reuse them and not introduce overlapping codes. + +### Reservations + +- The `events/` method prefix and the `notifications/events/` notification prefix are reserved for this extension. +- The label `io.modelcontextprotocol/events` is reserved for this extension. +- The `eventsListChanged` field of the `subscriptions/listen` notification filter is reserved for this extension. +- The HTTP header `X-MCP-Subscription-Id`, and the well-known path `/.well-known/mcp-webhook-receiver.json`, are reserved for this extension. + +## Security Considerations + +### Threat model + +The table lists the threats this extension is designed to defend against, and the mechanism that addresses each. Payload and authorization threats apply to all delivery modes. The rest are specific to webhook mode, which is the only mode that makes outbound requests to client-supplied URLs. + +| Threat | How it is addressed | +| --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Prompt injection through event payloads | Payloads are untrusted data. Clients sanitize or sandbox them before the LLM, as with tool results, and servers keep payloads minimal to shrink the injection surface. ([Untrusted payloads](#event-payloads-are-untrusted-data), [Payload minimality](#payload-minimality)) | +| Exposure of PII or sensitive data in event infrastructure (logs, queues, buffers) | Payload minimality: deliver only triage fields, such as sender, subject and ID, and fetch full content through tools on demand. ([Payload minimality](#payload-minimality)) | +| Unauthorized subscription, or continued delivery after access is revoked | A permission check at subscribe time (`Forbidden`), periodic re-verification at delivery time, and a `terminated` signal that ends the subscription when access is lost. ([Authorization](#authorization)) | +| Treating event receipt as authority to act | Action-time authorization: the agent's response to an event goes through normal MCP authorization, and receipt grants no privilege. ([Authorization](#authorization)) | +| SSRF and DNS rebinding (the server coerced into requesting internal hosts) | IP validation at delivery time against the IANA special-purpose registries, connecting to the validated IP with the original Host and SNI, and no redirects. Optionally a callback-URL allowlist. ([SSRF prevention](#webhook-security)) | +| Reflection and amplification DDoS (an attacker subscribes a victim's URL) | Mandatory endpoint verification before delivery is activated, cached per `(principal, url)`, with subscribe and per-destination rate limits. ([Endpoint verification](#webhook-security)) | +| Forged or spoofed deliveries (the endpoint deceived into processing fake events) | A per-subscription HMAC (Standard Webhooks `v1,`), which the receiver verifies before processing. ([Signature scheme](#webhook-security)) | +| Server impersonation (the endpoint cannot tell which server sent a delivery) | Optional asymmetric signing (`v1a,`) with the public key anchored to the server's trusted origin, so that gateways can allowlist known servers. ([Server identity](#webhook-security)) | +| Replay of captured deliveries | A `webhook-timestamp` freshness window (reject after 5 minutes), `webhook-id` deduplication, and a single-use, short-lived challenge nonce. ([Signature scheme, Endpoint verification](#webhook-security)) | +| Leakage of a signing secret | Secrets per subscription limit the blast radius. Rotation is client-driven with a dual-sign grace window, and asymmetric signing is optional defence in depth. ([Secret rotation, Server identity](#webhook-security)) | +| Eavesdropping in transit (payloads and `delivery.secret`) | TLS is required. Callback URLs are `https` only, and a non-`https` subscribe is rejected. ([TLS requirement](#webhook-security)) | +| Cross-tenant subscription tampering (guessing the tuple to unsubscribe or rotate another tenant's secret) | Webhook requires an authenticated principal, subscription identity includes `principal`, and the derived `id` is a routing handle that is not a capability. ([Subscription identity](#subscription-identity)) | +| Response oracle, or probing internal services through error detail | `deliveryStatus.lastError` is a fixed category string only, and never raw endpoint bodies, headers or status lines. ([Webhook delivery status](#webhook-delivery-status)) | +| Server-side resource exhaustion (subscription flooding) | `ResourceExhausted` limits. Webhook subscriptions expire without a refresh at the TTL the server granted, and a server that grants long or no-expiry TTLs explicitly accepts the retention burden. ([Error Handling](#error-handling), [Subscription TTL](#subscription-ttl)) | + +### Event payloads are untrusted data + +Event payloads MUST be treated with the same caution as tool results. They originate from external systems and may contain: + +- Prompt injection attempts, such as an email subject line that contains "ignore all previous instructions". +- Malformed or malicious data. +- PII that should not be forwarded or logged. + +Clients SHOULD sanitize or sandbox event payloads before presenting them to an LLM, following the security model the specification already defines for tool results. + +### Payload minimality + +Servers SHOULD keep event payloads minimal: enough to identify and triage the event, and not the full content. For example, an email event should include the sender, the subject and a message ID, but not the full body. The client can use tools to fetch full content when it needs it. This reduces PII exposure in event infrastructure (logs, queues, buffers) and limits the injection surface. + +### Authorization + +**Subscribe time.** When the caller is authenticated, the server MUST verify that the principal has permission to subscribe to the requested event type with the given arguments. For example, a Slack server verifies that the user has access to the specified channel. Unauthenticated servers, which may offer poll and push but not webhook, apply whatever server-side policy they choose, including accepting all subscriptions. + +**Delivery time.** The server SHOULD periodically re-verify permissions. If the user's access is revoked, for example because they were removed from a Slack channel, the server terminates the subscription with the signal for its mode (see [Subscription Termination](#subscription-termination)). + +**Action time.** Receipt of an event does NOT constitute authorization to act. The agent's response to an event, such as calling a tool, goes through normal MCP authorization. + +### Governance + +This extension does not mandate specific governance mechanisms, but it is designed to enable them. + +- **Audit.** The client owns all subscription state. Enterprise agent runtimes can inspect the client SDK's subscription registry and log all event-triggered actions. +- **Policy.** Clients SHOULD support policy evaluation between event receipt and action execution. The policy language is an application concern and not a protocol concern. +- **Kill switch.** For poll, stop polling. For push, abort the request stream (HTTP) or send `notifications/cancelled` (stdio). For webhook, call `events/unsubscribe` for immediate termination, or stop refreshing and let the subscription expire at its TTL. No-expiry subscriptions have to be unsubscribed explicitly. +- **Rate limiting.** `nextPollMs` lets servers control polling frequency dynamically, and clients SHOULD respect it. Enterprise deployments may impose additional rate limits.