Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
38 commits
Select commit Hold shift + click to select a range
ea5e7c5
feat(core): Events extension (SEP-3415) wire schemas and core subpath
KKonstantinov Nov 18, 2026
235ecfa
feat(core-internal): Events shared internals: EventsError, canonical …
KKonstantinov Nov 18, 2026
b25890a
feat(server): EventsExtension registration, attach, events/list and e…
KKonstantinov Nov 18, 2026
65be2c3
feat(server): events/poll with emit buffer, cursors and poll leases
KKonstantinov Nov 18, 2026
ba9d898
feat(server): events/stream push delivery, streamed in every HTTP res…
KKonstantinov Nov 18, 2026
367f4f8
fix(server): fresh cursor on a truncated events/stream batch
KKonstantinov Nov 18, 2026
a5804c1
feat(server): Events webhook delivery engine
KKonstantinov Nov 18, 2026
fb1a345
fix(server): retry webhook control envelopes, bound parked deliveries
KKonstantinov Nov 18, 2026
db11773
feat(server): Events webhook subscriptions, InMemoryWebhookSubscripti…
KKonstantinov Nov 18, 2026
1491982
fix(server): count in-flight webhook creates and key ids on client ar…
KKonstantinov Nov 18, 2026
6364fe8
feat(server): SSRF-hardened nodeWebhookSender at ext/events/node
KKonstantinov Nov 18, 2026
3649309
fix(server): classify NAT64 well-known prefix by its embedded IPv4
KKonstantinov Nov 18, 2026
199befc
feat(server): validate Mcp-Param headers on events requests
KKonstantinov Nov 18, 2026
d328c39
feat(client): internal long-lived request streams
KKonstantinov Nov 18, 2026
49324ed
fix(client): end request streams from a snapshot and always run base …
KKonstantinov Nov 18, 2026
cc6791c
feat(client): EventsClientExtension with list, gating, mode selection…
KKonstantinov Nov 18, 2026
9fad019
fix(client): end event subscriptions on close and recover from stale …
KKonstantinov Nov 18, 2026
9aa9fbc
feat(client): Events push driver and shared recovery rules
KKonstantinov Nov 18, 2026
4641d0d
fix(client): never re-arm the push dead-stream timer after the stream…
KKonstantinov Nov 18, 2026
23225ed
feat(client): Events webhook driver, receiver and shared driver recovery
KKonstantinov Nov 18, 2026
28a20fe
fix(client): serialize identical webhook subscriptions and release on…
KKonstantinov Nov 18, 2026
a387a34
fix(server): gate events on the session's era and defer module-scope …
KKonstantinov Nov 18, 2026
3bd3c4d
test: Events integration and wire-behaviour suites
KKonstantinov Nov 18, 2026
9459651
test(e2e): Events requirements and scenarios
KKonstantinov Nov 18, 2026
2236e1e
test(e2e): keep shared Events requirement wording to the SEP, add SDK…
KKonstantinov Nov 18, 2026
7533cd6
test(e2e): test the Events capability rule through the listen acknowl…
KKonstantinov Nov 18, 2026
b1eaf1f
fix(server): no SSE comment keepalive on events/stream
KKonstantinov Nov 18, 2026
e33b525
test(conformance): Events fixture and client scenarios (local until r…
KKonstantinov Nov 18, 2026
847ce2d
fix(server): no truncated flag on a null cursor (non-replayable event…
KKonstantinov Nov 18, 2026
6f42772
fix: export Events types that exported symbols reference (typedoc)
KKonstantinov Nov 18, 2026
2cfacad
docs(events): example story, guides and changeset
KKonstantinov Nov 18, 2026
707e9b6
fix(events): final review fixes — non-replayable poll delivery, verif…
KKonstantinov Nov 18, 2026
c3e6ed4
Merge origin/main into feature/ext-events-sep-3415
KKonstantinov Nov 19, 2026
8d3ebd5
feat(events): install Events through the extensions option, drop attach
KKonstantinov Nov 19, 2026
1ac5415
fix(events): address review findings on delivery, limits and DNS
KKonstantinov Nov 19, 2026
0791753
fix(events): second review round — DNS deadline and pinning, delivery…
KKonstantinov Nov 19, 2026
88f5c1b
fix(events): bound held webhook messages and throttle abandon reports
KKonstantinov Nov 19, 2026
5ebb589
fix(events): third review round — auth and retry endings, gaps, backl…
KKonstantinov Nov 19, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions .changeset/events-extension.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
---
'@modelcontextprotocol/core': minor
'@modelcontextprotocol/core-internal': minor
'@modelcontextprotocol/client': minor
'@modelcontextprotocol/server': minor
---

author: @KKonstantinov

Add the Events extension (SEP-3415), reachable through new `ext/events` subpaths; package root exports are unchanged. The whole Events API is experimental and may change in a minor release.

- `@modelcontextprotocol/server/ext/events`: `EventsExtension`, whose `registerEvent(name, definition)` takes a `check` function or `emitOnly: true` and returns a handle with `update()`, `remove()` and `terminate()` (and `emit()` for emit-only types), and which serves `events/list`, `events/poll`, `events/stream`, `events/subscribe` and `events/unsubscribe` on every `McpServer` constructed with it in the `extensions` option; `InMemoryWebhookSubscriptionStore`; `EventsError`; the types `EventContext`, `CheckContext`, `EventInput`, `EventResult`, `EventDefinition`, `CheckEventDefinition`, `EmitOnlyEventDefinition`, `EventHandle`, `EmitOnlyEventHandle`, `EventsOptions`, `EventsErrorKind`, `WebhookSender`, `WebhookSendRequest`, `WebhookSendOutcome`, `WebhookSubscriptionStore` and `WebhookSubscriptionRecord`; and the wire types and constants. Push streams under every `createMcpHandler` `responseMode`, `'json'` included. Webhook delivery is on when `webhookTtlMs`, `webhookSender` and `getPrincipal` are all set; `trustedOrigins` exempts exact origins from the `https` and private-address rules, for development.
- `@modelcontextprotocol/server/ext/events/node`: `nodeWebhookSender()`, a `WebhookSender` for Node.js that requires `https`, resolves the host at every send, refuses IANA special-purpose addresses, follows no redirects and gives up after 5 seconds.
- `@modelcontextprotocol/client/ext/events`: `EventsClientExtension`, passed in one `Client`'s `extensions` option, with `list()`, `subscribe({ name, arguments, delivery?, cursor?, maxAgeMs?, onGap? })` and `createWebhookHandler()`; `NoCompatibleDeliveryModeError`; `EventsError`; the types `EventsClientOptions`, `SubscribeOptions`, `EventSubscription` (an async iterable with `cursor`, `deliveryMode`, `deliveryStatus` and `cancel()`) and `EventsErrorKind`; and the wire types and constants. A subscription prefers webhook (when configured), then push, then poll.
- `@modelcontextprotocol/core/ext/events`: the wire constants, a Zod schema and inferred type for every Events wire shape, and `EventsCapabilitySchema`, `EventsCapability` and `eventsCapabilityOf`.

Clients now send `Mcp-Name` on `events/poll`, `events/stream`, `events/subscribe` and `events/unsubscribe`, and `createMcpHandler` requires it on 2026-07-28 (`400` / `-32020` when it is missing or does not match `params.name`), whether or not the server serves Events.

Events is served and used on protocol 2026-07-28 only. Not included: `notifications/events/list_changed`, and webhook grants without expiry (`refreshBefore: null`). With several replicas sharing a `WebhookSubscriptionStore`, `emit()` reaches push streams and the poll buffer only on the emitting process, and the `check` loop of a webhook subscription may run on more than one replica.
4 changes: 3 additions & 1 deletion docs/.vitepress/nav.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ export const guideSidebar: DefaultTheme.SidebarItem[] = [
{ text: 'Tools', link: '/servers/tools' },
{ text: 'Resources', link: '/servers/resources' },
{ text: 'Skills', link: '/servers/skills' },
{ text: 'Events', link: '/servers/events' },
{ text: 'Prompts', link: '/servers/prompts' },
{ text: 'Completion', link: '/servers/completion' },
{ text: 'Logging, progress, cancellation', link: '/servers/logging-progress-cancellation' },
Expand Down Expand Up @@ -58,7 +59,8 @@ export const guideSidebar: DefaultTheme.SidebarItem[] = [
{ text: 'Machine auth', link: '/clients/machine-auth' },
{ text: 'Middleware', link: '/clients/middleware' },
{ text: 'Caching', link: '/clients/caching' },
{ text: 'Skills', link: '/clients/skills' }
{ text: 'Skills', link: '/clients/skills' },
{ text: 'Events', link: '/clients/events' }
]
},
{ text: 'Protocol versions', link: '/protocol-versions' },
Expand Down
122 changes: 122 additions & 0 deletions docs/clients/events.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
---
shape: how-to
---

# Events

::: warning Experimental
Events (SEP-3415) is an accepted MCP extension. Its SDK API is new and may change in a minor release.
:::

`EventsClientExtension` subscribes to a server's event types, and you read each **subscription** with `for await`.

```ts source="../../examples/guides/clients/events.examples.ts#subscribe_basic"
import { Client } from '@modelcontextprotocol/client';
import { EventsClientExtension } from '@modelcontextprotocol/client/ext/events';

const events = new EventsClientExtension();
const client = new Client({ name: 'ops-console', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' }, extensions: [events] });
await client.connect(transport);

const subscription = await events.subscribe({ name: 'ticket.updated', arguments: { queue: 'billing' } });
for await (const event of subscription) {
console.log(event.name, event.data);
break;
}
```

When a ticket in the billing queue opens, it prints:

```text
ticket.updated { ticketId: 'T-7', status: 'open' }
```

Pass the extension in the client's `extensions` option: the client calls its `setup` while it is constructed, which ties the extension to that one client. `subscribe()` resolves once its first exchange with the server succeeds, and the subscription starts from now unless you pass a `cursor`. `list()` returns the server's event types with their schemas and delivery modes.

Each subscription takes the first delivery mode the event type offers out of webhook (when you configure it), push and poll; `delivery` forces one, and `subscription.deliveryMode` says which it got. Without `delivery`, when a push subscription's first stream fails before its first `notifications/events/active` with anything but an `EventsError` (no valid `active` within the request timeout, say, behind a host that buffers whole responses), the client reports the failure to its `onerror` and subscribes by poll instead, if the event type offers poll. The loop is the same in every mode, drops a repeated `eventId`, and leaving it cancels the subscription.

::: info
Events is used on protocol 2026-07-28 only, so create the client with `versionNegotiation: { mode: 'auto' }` or a pin — see [Protocol versions](../protocol-versions.md).
:::

## Resume from a saved cursor

`subscription.cursor` is the newest cursor that is safe to save; pass it back as `cursor` to pick up where the loop stopped.

```ts source="../../examples/guides/clients/events.examples.ts#subscribe_cursor"
// Save the cursor; it covers every event the loop finished with.
const saved = subscription.cursor;

// Later, maybe in a new process: resume from the saved cursor.
const resumed = await events.subscribe({ name: 'ticket.updated', arguments: { queue: 'billing' }, cursor: saved });
for await (const event of resumed) {
console.log(event.name, event.data);
if (event.data.status === 'closed') break;
}
```

Meanwhile the ticket was closed. The resumed subscription delivers the event the first loop broke on again, then the change it missed:

```text
ticket.updated { ticketId: 'T-7', status: 'open' }
ticket.updated { ticketId: 'T-7', status: 'closed' }
```

The cursor covers the events the loop finished with, and the loop finishes with an event when it asks for the next one, so a resumed subscription can repeat the last event: handle events idempotently, or skip an `eventId` you have handled. An event type that cannot resume has a `null` cursor, and there is nothing to save.

`onGap` receives the fresh cursor when events may have been skipped: the server reported `truncated`, or delivery started again from now after a schema change made the server refuse your cursor. Closing the client, or connecting it again, ends every subscription, and the loop rejects with an `SdkError` (`ConnectionClosed`). After reconnecting, subscribe again and pass the cursor you saved.

## Receive events by webhook

Give the extension a webhook URL and serve its receiver there.

```ts source="../../examples/guides/clients/events.examples.ts#webhook_receiver"
import { Hono } from 'hono';

const hooked = new EventsClientExtension({ webhook: { url: 'https://hooks.example.com/mcp/events' } });
const handleWebhook = hooked.createWebhookHandler();

// Serve the receiver at the webhook URL from any fetch-style server; here, Hono.
const app = new Hono();
app.post('/mcp/events', c => handleWebhook(c.req.raw));
```

With `webhook` set, a subscription prefers webhook wherever the event type offers it: the server POSTs each event to the URL, and the receiver checks the signature and routes the event into its subscription's loop. The client makes a `whsec_` secret for each server subscription (or takes one from `secretProvider`), answers the server's verification challenge, and refreshes the subscription before it expires. `subscription.deliveryStatus` holds the delivery health the server last reported.

Webhook subscriptions with the same name and arguments share one server subscription, and cancelling the last of them sends `events/unsubscribe`. The SDK's server accepts a webhook subscription only from an authenticated principal and answers `forbidden` otherwise. The receiver answers `503` to a subscription it does not know yet, and the server retries.

The receiver answers `2xx` once it has queued an event in memory, so events queued but not yet read by your loop are lost if the process exits. Subscribing again within the grant, while the server still delivers to the subscription, continues from the server's position rather than from your saved cursor.

## Handle errors

Catch `EventsError` around `subscribe()` and the loop; `kind` says what went wrong.

```ts source="../../examples/guides/clients/events.examples.ts#errors"
import { EventsError } from '@modelcontextprotocol/client/ext/events';

try {
const refused = await events.subscribe({ name: 'ticket.updated', arguments: { queue: 42 } });
for await (const event of refused) console.log(event.data);
} catch (error) {
if (!(error instanceof EventsError)) throw error;
console.log(error.kind);
}
```

The server rejects `queue: 42` against the event type's `inputSchema`, so it prints:

```text
invalidParams
```

`subscribe()` rejects with an `EventsError` when the server does not list the event type or refuses the subscription (`notFound`, `invalidParams`, `forbidden`, `unsupported`, `resourceExhausted` or `callbackEndpointError`), with an `SdkError` when the exchange fails in the SDK, such as a closed connection, an HTTP error status other than `5xx` and `429`, or a push stream with no valid `notifications/events/active` within the request timeout, and with the transport's auth failure (such as `UnauthorizedError` for a `401` the `authProvider` cannot resolve) or a `ProtocolError` `-32601` from a server that does not serve the method; other failures of the first exchange, such as a transport error, an HTTP `5xx` or `429`, or another JSON-RPC error, are retried in the background. The server's webhook verification limit (`resourceExhausted` with `data.limit: 'verification'`) is one of those: the client subscribes again after `data.retryAfterMs` (or its usual backoff without one), before and after the first exchange. A push subscription that can fall back to poll, as above, does so instead on any of these failures but an `EventsError`, an auth failure, a `-32601` or a closed connection. Each retried failure, such as a transport error, an HTTP error status, another JSON-RPC error or the verification limit, before the first exchange succeeds or after, goes to the client's `onerror`: the first at once, then at most one report a minute with how many were retried since. A push stream that ends or goes silent is reopened without a report, and so is a request retried after the event types are listed again. When the server refuses the delivery mode the client selected (`unsupported` for `deliveryMode`, say after a deploy that dropped it), the client lists the event types again once and subscribes in the mode that listing selects; a mode you force with `delivery` is not changed. Once subscribed, the loop ends with an `EventsError` when the server ends the subscription, such as `forbidden` when access is revoked, and with an auth failure or a `-32601` as `subscribe()` would reject. A `notFound`, or an `unsupported` for a schema change, makes the client list the event types again and carry on while the type is still offered in that mode.

`NoCompatibleDeliveryModeError` means no delivery mode the event type offers is usable here: webhook needs the `webhook` option, and `delivery` narrows the choice to one mode. Against a server without Events, or on a connection older than 2026-07-28, `events.supported` is `false`, and `list()` and `subscribe()` throw `SdkError` (`CapabilityNotSupported`). An error thrown from `onGap` goes to the client's `onerror`.

## Recap

- `new EventsClientExtension()` in the client's `extensions`, then `connect()`, `subscribe({ name, arguments })` and `for await`.
- The loop is the same in every mode, and leaving it cancels the subscription.
- `subscription.cursor` is safe to save; pass it back as `cursor` to resume, and expect the last event again.
- `webhook: { url }`, with `createWebhookHandler()` served at that URL, turns on webhook delivery.
- `subscribe()` and the loop fail with an `EventsError` whose `kind` says why.
Loading
Loading