FinalExtensions Track
This SEP has reached Final status and is preserved as a historical record of
the design as accepted. Changes made to the protocol after finalization are
not reflected here. Refer to the current
specification and its changelog for authoritative
requirements.
Abstract
This SEP defines Events, an extension that 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 withevents/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) is request/response. Push (events/stream) is a long-lived request that delivers events as notifications. Webhook (events/subscribe) registers an https callback URL, and the server POSTs signed events to it under a TTL that the client refreshes. An opaque, server-defined cursor lets a client resume after a disconnect. Replay is optional per event type, and truncated: true signals that events were skipped.
The client owns the canonical list of subscriptions. Authorization uses the same MCP principal as tools, and event payloads are untrusted data, like tool results.
Motivation
MCP is request-driven: a user or a model asks, and a server answers. Agents increasingly need to act on things that happen when nobody is asking, such as a new email, a push to a repository or a production incident. Today a client learns about server-side changes only by polling or by holding a connection open, and there is no standard way for a server to say what can be watched, with which parameters, and what will be delivered. The notifications MCP already has do not cover this.- They are content-addressed and carry no parameters.
notifications/resources/updatedsays that a URI changed, and thelist_changedfamily says that a list changed. Neither can express “a P1 incident was created for service X”, because there are no subscription arguments, no payload schema and no payload. - They need a live connection. They are delivered only on an open
subscriptions/listenstream. A client that is not connected receives nothing, and there is no way to deliver to a client that cannot hold a stream open. - They cannot be resumed. There is no cursor, so whatever happens during a disconnect is lost, and the client cannot tell that it missed anything.
Specification
This extension is defined for protocol revision2026-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
Resultand carriesresultType: "complete". - Error codes are referred to by name. Error Handling gives the numeric codes.
Extension Identifier
This extension is identified asio.modelcontextprotocol/events.
Working Group and Extension Maintainers
The extension is owned by the Triggers & Events Working Group. Its Extension Maintainers are the Working Group leads, currently Clare Liguori (@clareliguori) and Peter Alexander (@poita). The extension is incubated inexperimental-ext-triggers-events. When this SEP is accepted, the specification is published in an official extension repository as SEP-2133 describes.
Capability Negotiation
Events is declared through Extension Negotiation: the identifier appears as a key in theextensions field of capabilities, mapped to the extension’s settings object.
A server advertises event support in the capabilities it returns from server/discover:
listChanged (boolean, optional, default false), which says whether the server sends notifications/events/list_changed (see 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:
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/pollwith the event name, arguments and cursor. There is no separate subscribe step: the first poll with anullcursor bootstraps the subscription. The server holds no protocol-required state. - Push. The client opens a long-lived
events/streamrequest 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/subscribeto 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). Unless it was granted no expiry, the client refreshes by callingevents/subscribeagain 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.
Listing Available Events
Request: events/list
Response
deliverylists 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.inputSchemais 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 theinputSchema/argumentspairing on tools. As on tools, a property MAY carry anx-mcp-headerannotation, which mirrors that argument into an HTTP header (see Custom headers from subscription arguments).payloadSchemais a JSON Schema fordatain delivered events.
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.
inputSchemaSHOULD NOT be tightened so that previously acceptedargumentsbecome invalid. A webhook refresh re-sends them, and would fail withInvalidParams.
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:
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 itsinputSchema 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): notifications/events/terminated on push streams, and a terminated envelope to webhook subscriptions.
The error is:
NotFoundwithdata: {"kind": "event"}when the type was removed.Unsupportedwithdata: {"feature": "payloadSchema" | "inputSchema", "reason": "schema_changed"}when it was changed in place.
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’sevents[], 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). Webhook delivery also sends control bodies that are not events (see Non-event webhook bodies).
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 callsevents/poll at the interval the server recommends. This is a protocol-level operation, not an LLM tool call.
Request: events/poll
Each events/poll request carries one subscription. A client with several subscriptions runs one poll loop per subscription.
Response
cursoris opaque to the client. The client stores it and passes it back on the next poll. In the request,nullmeans “start from now”: the server returns no events and a fresh cursor for later polls. In the response, the server MAY returncursor: nullfor an event type that does not support replay. The client then has nothing to persist and always polls withnull(see Cursor Lifecycle).maxEventsis 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 setshasMore: true. If it is omitted, the server uses its own default.hasMoresays whether more events are available beyond the returned batch. When it istrue, the client SHOULD poll again immediately with the updated cursor, ignoringnextPollMs, to drain the backlog. When it isfalse, the client waitsnextPollMsbefore the next poll.nextPollMslets 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 whenhasMoreistrue. 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 withtruncated: true. Clients SHOULD apply a configurable floor (default 1000 ms) so that a misbehaving server cannot induce a tight loop.- An empty
eventsarray 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).
- 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-livedevents/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/streamrequest is a POST that returns an SSE response stream. The client cancels by aborting the request stream (TCP close on HTTP/1.1,RST_STREAMon HTTP/2). No explicit cancellation message is needed. - stdio. The
events/streamrequest 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 sendingnotifications/cancelledwith the request’sid.
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.
Request: events/stream
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.
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).
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).
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
StreamEventsResultis an empty result that carries onlyresultTypeand the subscription ID in_meta, mirroringSubscriptionsListenResult. 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}}}.cursoris the position the server has checked up to, so the client’s persisted cursor advances even when no events match (see Cursor Lifecycle). It isnullfor event types that do not support replay. On Streamable HTTP the heartbeat is an SSEdata: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
heartbeatMsin theevents/streamparams. The server grants one inheartbeatMson everynotifications/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 wheneverheartbeatMspasses without any other message on the stream. Clients SHOULD NOT apply their default request timeout toevents/stream: the heartbeat is the liveness signal. A client that has received no message on the stream for three times the grantedheartbeatMs, counted fromnotifications/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/cancelledwith therequestIdof theevents/streamrequest. In both cases the server MUST stop delivering events and release the associated resources. On stdio, the server MAY then send theStreamEventsResult. 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/streamrequests 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 exemptevents/streamfrom 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/streamwith 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 acursor 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).
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). 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: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) refreshes the TTL and updates the mutable fields. This is how clients keep subscriptions alive.
events/subscribeis used only for webhook delivery. Poll and push do not need it.delivery.secretis 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 prefixwhsec_followed by the base64 encoding of 24 to 64 random bytes. Servers MUST reject other values withInvalidParams. 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 theX-MCP-Subscription-Idheader 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.nullmeans “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), 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 isnullfor 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, ornullfor no expiry. Unless it was granted no expiry, the client MUST callevents/subscribeagain with the same subscription key beforerefreshBeforeto keep the subscription alive. The server grants a TTL again on each refresh. See Subscription TTL.events/subscribeis 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). 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 explicitttlMs: nullrequests 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 grantedrefreshBeforeand schedules its refresh loop from that, so a clamped grant is not an error, and there is no rejection path for TTL values.refreshBefore: nullgrants no expiry. The subscription persists untilevents/unsubscribeor server-initiated termination. A server MUST NOT returnnullunless the client suggestedttlMs: null, because no expiry exceeds every finite suggestion. A server that is unwilling to grant it returns a finiterefreshBefore, which the client treats like any other grant.
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
terminatedenvelope when it does.
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). 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 whichevents/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:
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:- Headers. Deliveries follow the Standard Webhooks signature scheme (see Signature scheme).
X-MCP-Subscription-Idis an MCP-specific header that carries the subscriptionid, 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 whosewebhook-timestampis more than 5 minutes old, and SHOULD deduplicate onwebhook-id, which identifies the delivered message and not the event. Each retry attempt keeps thewebhook-idand regenerates the timestamp and signature. eventIdin the body identifies the upstream event. A receiver that deduplicates by it MUST scope that to the subscription (X-MCP-Subscription-Id): the sameeventIddelivered on two subscriptions is two deliveries, and both are processed.cursorin 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 includecursor_Nin 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 sendcursor: nullfor event types that do not support replay, in which case there is no recovery point to persist. The endpoint MUST makecursorandeventIdavailable 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-
2xxresponses. 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 useswebhook-idto discard retried deliveries, andtimestampfor ordering if it needs it. Because the payloadcursoris 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, responds410 Gone. The server MUST treat410as a non-retryable failure for that delivery (like413, see Delivery profile), without affecting the subscription itself. - Acknowledgement semantics. A
2xxresponse from the webhook endpoint signals that the event has been accepted and the server need not retry it. The endpoint SHOULD NOT return2xxuntil 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, return2xx, 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
idit has not yet been told to route, for example because the subscribe response has not propagated to the gateway, SHOULD return a retryable status (503or425 Too Early). The server’s retry and backoff redelivers once the receiver is ready.webhook-iddeduplication and cursor replay make this safe. This guidance covers event deliveries and thegapandterminatedenvelopes. It does not cover averificationenvelope, which on a first subscribe always arrives before the receiver has been given theid(see Endpoint verification). - 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 (setsactive: 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 aterminatedenvelope when it does (see Subscription TTL).
Non-event webhook bodies
In addition toEventOccurrence 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_<type>_<random>, 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.
Webhook delivery status
Theevents/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.
deliveryStatus is OPTIONAL, and servers MAY omit it entirely. When it is present:
activesays whether the server is currently delivering events.falsemeans it has suspended retries after repeated failures, and the refresh that returned this status has just reactivated it.lastErrorMUST be a server-generated category string, one ofconnection_refused,timeout,tls_error,http_4xx,http_5xxorchallenge_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 asdata.reasonon aCallbackEndpointErrorreturned synchronously fromevents/subscribe.throttled(optional boolean) distinguishes active rate-limiting from failure-driven suspension.truemeans 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) accompaniesthrottledas 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 and IPv6 Special-Purpose Address Registries, unless they are explicitly configured to allow them. Illustrative examples are127.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:
- A verification handshake. Before activating, the server POSTs a
verificationcontrol envelope that carries a single-use, short-livedchallengenonce, signed and headed like any delivery. The endpoint proves intent by echoing the nonce in a2xxbody ({"challenge":"<nonce>"}), which the server compares in constant time. - The URL matching a server-configured allowlist.
- 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.
- A receiver-published well-known document. The callback URL’s
httpsorigin 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.
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 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, which adds the extensionsInfo map to Server Card remotes. It is distinct from the OAuth jwks_uri (RFC 8414), 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.
- Every delivery MUST include
webhook-id,webhook-timestampandwebhook-signature.webhook-ididentifies 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 fromeventId, which comes from the upstream, may not be header-safe, and is shared by every subscription the event matches. Control envelopes use the formmsg_<type>_<random>.webhook-timestampis the Unix timestamp of the request in seconds. - The signature is
HMAC-SHA256(secret, webhook-id + "." + webhook-timestamp + "." + body), encoded as base64 with av1,prefix.bodyis the raw HTTP request body bytes exactly as received, before any parsing or re-serialization. Thewebhook-id + "." + webhook-timestamp + "."prefix is UTF-8.secretis the base64-decoded bytes of the value after thewhsec_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,<sigA> v1,<sigB>) 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-timestampis more than 5 minutes old. - Deliveries MUST also include
X-MCP-Subscription-Id(the subscriptionid), 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.
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
POSTonly. - Content-Type.
application/json. - Required headers.
webhook-id,webhook-timestamp,webhook-signatureandX-MCP-Subscription-Idare 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. Receivers and intermediaries MAY reject larger bodies with
413 Payload Too Large. Servers MUST treat413as a non-retryable failure for that event. - TLS.
httpsis mandatory fordelivery.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. 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
egressIpRangesmember ofremotes[].extensionsInfo["io.modelcontextprotocol/events"].webhooks, as an array of CIDR strings. This location depends on ext-server-card#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).
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 returncursor: 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: trueon 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:, Slackoldest=, KafkaoffsetsForTimes) SHOULD seek directly. Others MAY honormaxAgeMsby replaying fromcursorand discarding events whosetimestampis older than the floor. If that would be prohibitively expensive, such as a week-old cursor withmaxAgeMs: 300000, they MAY instead reset to now and returntruncated: 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 withtruncated: truewhen they do. maxAgeMsis ignored whencursorisnull, becausenullalready 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.
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.
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), or when the event type is removed or changed incompatibly (see Event type removal and breaking changes). The termination signal carries the same nestederror shape in every mode:
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.
eventIdfor 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
timestampfield. 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.
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 idempotentevents/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), which is part of what a server accepts by granting them.
Streamable HTTP: Routing Headers
Whenevents/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) 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-Nameheader is missing, or does not matchparams.name, is rejected with HTTP status400 Bad RequestandHeaderMismatch(-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’sinputSchema with the x-mcp-header annotation that the Streamable HTTP transport defines for tool parameters (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.
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) orevents/unsubscribeis sent over that transport, the client MUST set anMcp-Param-{Name}header for each annotated property that has a value inparams.arguments, encoded as the transport describes. - The constraints on
x-mcp-headervalues are those of the transport. A client MUST exclude an event type whose annotations violate them from the result ofevents/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 RequestandHeaderMismatch(-32020). A client that receives this error SHOULD callevents/listagain and retry with the headers the currentinputSchemacalls for. - Clients on other transports MAY ignore the annotation.
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
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 SEP requests the next five codes in the allocated range. The numbers above assume that -32020 to -32022 are the only codes allocated when this SEP is accepted, and are provisional until then. 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 thenotifications/events/notification prefix are reserved for this extension. - The label
io.modelcontextprotocol/eventsis reserved for this extension. - The
eventsListChangedfield of thesubscriptions/listennotification 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.
Rationale
These are the choices where reasonable alternatives existed. They are recorded so that reviewers can challenge the trade-off without having to derive the option space again.Choice of delivery modes
Three delivery modes: poll, push and webhook. This goes against MCP’s usual stance of offering one way to do a thing, and the cost is real: roughly three times the specification and SDK surface, two cursor placements and two subscription lifecycles. The extension pays it because the deployment topologies that events have to reach are disjoint, and dropping any mode strands a real population.- Poll is the floor. It works for stateless and serverless servers with no outbound HTTP and no long-lived connections, and for clients behind NAT with no public endpoint. Its latency is bounded by the polling interval.
- Push gets low latency for stdio servers, local agents and HTTP clients that can hold a stream open. The server has to keep a connection per subscription, which scale-to-zero and connection-capped deployments cannot do.
- Webhook gets low latency without a held connection. It requires the server to make outbound HTTP requests, and the client, or a proxy acting for it, to expose a reachable endpoint.
events/poll or events/stream request. Batching is a transport-level concern, and HTTP/2 multiplexing makes a request per subscription cheap. This avoids the protocol complexity that batching introduces: coalescing heterogeneous nextPollMs values, partial-failure result shapes, error routing per entry, and duplicate-ID handling. Clients with many subscriptions on HTTP/1.1 should expect to coalesce at the transport and not in the protocol.
A dedicated events/stream, and not a subscriptions/listen filter. The Tasks extension delivers notifications/tasks by adding a taskIds field to the subscriptions/listen filter, and push delivery of events could have done the same. It does not, for the same reason that requests are not batched. A push subscription has its own arguments, cursor, maxAgeMs, confirmation, gap signal, heartbeat cursor and termination error. Putting several of them on one shared stream brings back per-entry error routing and partial failure. A dedicated request per subscription keeps each of those scoped to one JSON-RPC request, and lets a client add or remove a subscription without reopening a stream that carries other notifications. The stream still follows the subscriptions/listen conventions (confirmation first, io.modelcontextprotocol/subscriptionId on every notification, an empty result on graceful close), so SDKs can share the machinery. Only notifications/events/list_changed, which has no per-subscription state, rides on subscriptions/listen.
Multimedia and high-throughput streams are out of scope. Streaming media has fundamentally different transport, framing and backpressure requirements. Designing for event rates at human and automation scale keeps the SDK surface tractable. A media primitive would be a separate proposal.
A new events/* primitive, and not an extension of resource subscriptions. Resources are content-addressed (a URI maps to a representation) and have no parameters or cursors. Bolting filter arguments, replay and three delivery modes onto them would distort that model more than a parallel primitive costs. Folding resource subscriptions into events later is left as an open question.
Cursors, replay and reliability
Reliable, ordered delivery is supported and not mandated. Genuine use cases need it, so the cursor abstraction makes at-least-once delivery with replay achievable when the upstream is durable. Many upstreams are push-only and have no history, and mandating reliability would force them to fake it. Servers may returncursor: null to opt out.
The protocol connects to many upstream systems (Gmail, Slack, PagerDuty and others), each with its own consistency model. A unified consistency model at the MCP layer would be either too weak to be useful or too strong to implement across such different backends. Servers that need stronger guarantees can implement them. A server that wraps a Kafka topic could expose partition offsets as cursors and provide exactly-once semantics within a partition. A database change-data-capture server could use LSNs as cursors and guarantee causal ordering. The cursor is opaque, so it can encode whatever the server needs: sequence numbers, timestamps or composite positions. For most agent use cases, such as reacting to new emails, triaging alerts and responding to messages, eventual consistency with deduplication is sufficient.
Replay is bounded by a time floor (maxAgeMs) only, with no count bound. A time-anchored start is the universal primitive across replayable systems: Kinesis AT_TIMESTAMP, JetStream by_start_time, Kafka offsetsForTimes, and seek-to-time in RabbitMQ, Pulsar and Pub/Sub. A count-bounded subscribe (“the newest N”) requires a backward seek that many upstreams cannot do cheaply, and it is ambiguous about which end it counts from.
The cursor advances during quiet periods. The heartbeat carries the cursor for push, the refresh response carries it for webhook, and poll already returns it on empty results. Without this, a long quiet stretch leaves the client holding a cursor older than the upstream’s retention window, which yields a spurious truncated: true even though nothing happened. This reuses existing periodic messages and adds no new traffic.
The heartbeat interval is suggested by the client and granted by the server. Both sides have constraints the other cannot see. A client on a flaky network wants to notice disconnects sooner, a mobile client wants fewer wake-ups, a server wants to bound the work spent on idle streams, and either may sit behind an intermediary that closes idle connections. A fixed interval suits none of them. The suggest-and-grant pattern used for webhook TTLs gives each side one knob and makes the server’s answer authoritative. The heartbeat does two jobs, liveness and cursor advancement. Only cursor advancement is specific to this extension, and liveness may move to the core protocol (see Open Questions).
eventId is assigned by the server, and SHOULD be the upstream’s stable identifier. Delivery of the same upstream event by two paths, such as a webhook emit and a poll backfill, has to collapse under client-side deduplication. A server SDK generates one only when the author supplies none.
webhook-id is separate from eventId. webhook-id is transport-level: it identifies one delivered message and lets receivers discard retries, as Standard Webhooks intends. eventId is application-level: it identifies the upstream event. One upstream event can match several subscriptions that deliver to the same receiver. If webhook-id were the eventId, a receiver deduplicating on webhook-id would accept the first delivery and silently drop the others. A server-generated webhook-id is also always header-safe and contains no ., so it cannot make the signed string ambiguous, which an upstream-controlled eventId could. Webhook infrastructure such as Svix generates webhook-id itself, so the separation is also what off-the-shelf senders do.
No protocol-level flow control. There is no credit-based or token-based backpressure in this revision. The dominant bottleneck in an MCP event pipeline is LLM inference: processing a single event may take seconds to minutes of model time. Compared with that, event delivery rates from typical upstream sources are negligible. The system is bound by the consumer and not by the producer. What exists today is sufficient:
- Transport-level backpressure. TCP flow control throttles the server when the client stops reading from the connection. On stdio, OS pipe buffers have the same effect.
- Server-controlled frequency. For push, the server controls how often it checks upstream sources and delivers events. For poll,
nextPollMslets the server throttle the client explicitly. - Webhook throttling visibility. A server that rate-limits its outbound webhook deliveries surfaces it through
deliveryStatus.throttledandretryAfterMson the next refresh. This is a visibility hint for the client and not a backpressure mechanism. - Client-side prioritization. When several events arrive while the LLM is busy, the client SDK can prioritize by event type, severity or recency. Head-of-line blocking, where an event that is slow to process delays the ones after it, is handled the same way: the SDK can keep a queue per subscription and let the agent framework process events concurrently or by priority.
maxEvents and hasMore. For now this is left to TCP backpressure and server-side pacing. If future use cases involve high-throughput event streams where producer-side backpressure or bounded replay becomes necessary, a credit-based flow control extension can be added without breaking the existing protocol.
Webhook design
Standard Webhooks is adopted as a profile (webhook-id, webhook-timestamp, webhook-signature, v1, HMAC, whsec_ secrets, multi-signature rotation). This gives off-the-shelf verifier libraries in most languages, and a defined asymmetric path (v1a,) for free. The trade-off is a dependency on an external community specification, but it is small, stable and pinnable, and it is not a one-way door.
The webhook secret is supplied by the client, REQUIRED, and per subscription. This avoids the write-back race after subscribe that server-generated per-subscription secrets have, and the out-of-band registration step that per-endpoint secrets need. The HMAC proves “this delivery is for a subscription that this endpoint originated”, and not merely “this came from the server”. That stops third-party deception. Third-party flooding is closed separately by mandatory endpoint verification.
Endpoint verification is mandatory before delivery is activated. HMAC stops deception but not flooding: an attacker can point a subscription at a victim’s URL, and the victim still receives every POST. A consent handshake, which is the pattern WebSub, SNS and Event Grid use, bounds attacker-induced traffic to one POST per (principal, victim-url). Scoping the cache per (principal, url) stops one principal’s verification from waiving the challenge for another. The allowlist, out-of-band and well-known paths cover receivers for which a runtime handshake is awkward, such as dashboard-registered apps and gateways that can prove control of their origin.
Server identity to the endpoint is optional asymmetric signing. Symmetric HMAC cannot prove which server sent a delivery, because the secret is shared with the endpoint, so gateways that allowlist known servers need asymmetric signatures. It is optional, to avoid imposing key management on simple and serverless servers. The key has to come from an origin the client already authenticates and not from the delivery, or the allowlist becomes trust-on-first-use.
Webhook subscription identity is (principal, delivery.url, name, arguments), webhook requires authentication, and the server-derived id is for routing only. The tuple is everything that semantically defines a subscription, so subscribe is naturally idempotent and there is nothing for the client to generate or persist. The derived id is a routing handle that is not a capability. Webhook requires an authenticated principal so that the tuple cannot be guessed by other tenants. Without it, anyone could unsubscribe another tenant or rotate its secret. Server-generated and client-generated id schemes were both considered, and both add state or entropy obligations that the tuple makes unnecessary.
Server-side subscription durability is controlled by the server through the TTL it grants. Push is scoped to the connection, poll is per request, and webhook durability is coupled to the TTLs the server grants. Clients hold the canonical subscription list and rebuild server state by resubscribing. A server that wants soft in-memory state grants short TTLs: a crash never orphans a client, and a vanished client never leaks resources. A server that grants long or no-expiry TTLs opts into persisting subscriptions for the granted lifetime. The trade-off is that there is no server-side “list all subscriptions” without enumeration per principal.
The client suggests the webhook TTL and the server’s grant is authoritative. The grant SHOULD only shorten the suggestion, except to clamp it up to a server minimum, and ttlMs: null may be granted as no expiry. The client knows its own lifetime best. A long-lived tenant that holds many subscriptions should not be forced into a refresh cadence the server invented, and SIP Expires and WebSub lease_seconds are precedents. The “less than or equal” rule keeps the server from delivering past the client’s expected lifetime, and the floor exception protects servers from refresh storms. No expiry is offered explicitly and not excluded. A one-year TTL is practically unlimited anyway, and being explicit lets the specification attach the real obligations (durable state, failure-based collection, no expectation of an unsubscribe) to the server that grants it.
https is a MUST for webhook callbacks. Both event payloads and the delivery.secret in the subscribe request would otherwise transit in cleartext. No legitimate remote-server deployment lacks TLS in 2026.
Error codes
Five general-purpose codes carry their specifics in typeddata, alongside the base InvalidParams. An earlier draft minted seven codes scoped to events (EventNotFound, TooManySubscriptions, EndpointVerificationFailed, InvalidCallbackUrl, SubscriptionNotFound, DeliveryModeUnsupported and others). Collapsing each family behind one general code with a typed data discriminator keeps the shared error range uncluttered, and lets future SEPs reuse codes and not mint new ones. Clients can still distinguish every case they act on, by code, by method or by data. Static request errors fold into InvalidParams. Whether to allocate new codes at all, or to fold these into InvalidParams as the core protocol did for resource-not-found, is an open question.
Relationship to existing primitives
- Resources.
notifications/resources/updatedis unchanged. Events are a separate primitive for domain-specific occurrences that do not map to a specific resource. Servers MAY implement resource watching through events, but the two mechanisms are independent. - Tools. Events and tools compose at the application layer. An event arrives, the agent reasons about it, and it may call tools in response. This extension does not prescribe how events are wired to tools.
- Prompts. Future work may add event-bound prompts, which are prompt templates designed to be instantiated when a specific event fires. They are not in scope here.
- Sampling. Events may trigger LLM reasoning. The client decides whether to invoke the model in response to an event, and the server does not control this.
Related work
SEP-2495 (Event-Driven Tool Invocation) addresses how a server-pushed event re-enters the LLM. That is the application-layer step this extension leaves to the client (see Delivering events to the model), and the two proposals are complementary.Out of scope for this revision
- Durable subscriptions with replay from before the subscription. There is no mechanism to replay events from before subscription time. Cursors represent “now” and forward.
- Message queue bindings. The extension does not define bindings for specific message queue systems (SQS, MQTT, Kafka, Pub/Sub and others). For high-availability delivery through message queues, deploy an MCP proxy that receives events by poll, push or webhook and writes to the organization’s queue infrastructure. The client reads from the queue with the queue’s native client. This keeps the protocol transport-agnostic while enabling any intermediary.
- A rich query language for arguments. Arguments are simple key-value pairs. There is no CEL, JSONPath or complex predicate language. Servers define their own argument semantics through
inputSchema. - Cross-server event routing. There is no mechanism for one server’s events to trigger another server’s tools. This is an application and orchestration concern.
- Event-bound prompts. Deferred to a future version.
- Guaranteed delivery. See Ordering and Delivery Guarantees.
- Event schema versioning. There is no
schemaVersionfield on event types or occurrences, and no version negotiation at subscribe time. This revision relies on additive schema evolution, plus server-initiated termination on removal or breaking change. An in-band schema fingerprint, such as apayloadSchemahash carried in_metaon the descriptor and echoed on eachEventOccurrence, is a possible additive follow-on for clients that want exact drift detection. It is best revisited once the core protocol settles tool naming and versioning.
Backward Compatibility
This extension is additive. It defines new methods underevents/, new notifications under notifications/events/, one new optional field on the subscriptions/listen filter, and five new error codes. It changes no existing message, and notifications/resources/updated and the list_changed notifications are unchanged.
- A server that does not offer the extension answers
events/*with-32601(Method not found), and a client that does not implement it never sends them. - The extension is not defined under protocol revision
2025-11-25or earlier. - Prototype implementations of the design sketch that preceded this SEP advertised a top-level
eventscapability, and at least one deployed client reads it. That key is not part of this extension. Implementations written against the sketch migrate to theextensionsentry in Capability Negotiation. The methods and payloads are otherwise as the sketch defined them, apart from the error code numbers and theresultTypefield that the2026-07-28revision requires on results.
Security Implications
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.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.
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). 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, callevents/unsubscribefor immediate termination, or stop refreshing and let the subscription expire at its TTL. No-expiry subscriptions have to be unsubscribed explicitly. - Rate limiting.
nextPollMslets servers control polling frequency dynamically, and clients SHOULD respect it. Enterprise deployments may impose additional rate limits.
Reference Implementation
SEP-2133 requires a reference implementation in an official SDK before an Extensions Track SEP is reviewed. The following exist today:- Server and client, on the official TypeScript SDK. typescript-sdk#3209 implements the extension on both the server and the client, with all three delivery modes (poll, push and webhook), under experimental
ext/eventssubpaths. It is in review. - Server, on the official Python SDK.
mcp-webhook-eventsaddsevents/list,events/subscribeand signed webhook delivery on top of the Python SDK without forking it. A field report describes it interoperating end to end with a deployed third-party client over webhook delivery, including the verification handshake. - Conformance. Conformance suites for this SEP are open for review: five server scenarios (discovery, poll, push, webhook subscription and webhook delivery) in conformance#521, and four client scenarios in conformance#541, which is stacked on #521. Each check quotes the requirement of this SEP that it grades.
- Field report. A report on stdio restart recovery is in the Working Group repository (#6).
Open Questions
- How should the client SDK expose events to agent frameworks? As injected context, as a special message type, or as a callback like a tool call? This is an SDK design question and not a protocol question, but guidance would be useful.
-
Should resource subscriptions and
list_changednotifications be re-expressed as events? The existingresourceSubscriptionsfilter andnotifications/resources/updatedflow, and thenotifications/{tools,resources,prompts}/list_changedfamily, are effectively a special-cased, push-only event channel. Folding them into this primitive would give them cursors, poll and webhook delivery, and replay for free, and would remove a parallel mechanism from the specification. An example is a reservedmcp.resource.updatedevent type whose arguments are{uri}, withmcp.{tools,resources,prompts}.list_changedevent types. The cost is a migration path for existing clients, and the question of whether the protocol should reserve anmcp.*event-name prefix at all. -
Can a single subscription span several event names with one cursor? (Wire-breaking if adopted.) Several upstreams expose one ordered change feed that yields several event types. A Kubernetes watch on a namespace produces pod, deployment and event objects, a Kafka consumer on one topic yields heterogeneous message kinds, and a Slack Socket Mode connection delivers messages and reactions. Under the current model, a client that wants both
k8s.pod_phase_changedandk8s.oom_killedopens two subscriptions with two cursors, and the server runs two parallel watches against the same API server. The options are: (a) keep subscriptions per event name and let the server SDK coalesce upstream connections internally, with no protocol change but more SDK complexity; (b) allow a subscription’snameto be an array, so that one cursor covers a set of event types, which is a protocol change with a simpler server and a client that has to demultiplex; (c) introduce an event-group concept at registration time. A TypeScript SDK stress test hit this with both Slack and Kubernetes. -
Should MCP task state changes be exposed as events? Clients currently learn of task state transitions by polling
tasks/get, or throughnotifications/taskson a livesubscriptions/listenstream. A reservedmcp.task.updatedevent type (arguments{taskId}, payload{status, progress?, result?}) would let a client that started a task and disconnected receive the completion by poll or webhook. This serves “kick off a long job, close the laptop, get notified when done”. The considerations are the same as in question 2: a reservedmcp.*prefix, a migration path, and whether one mechanism subsuming another is worth the coupling. A draft is in experimental-ext-triggers-events#2. -
Should the error codes be new allocations, or
InvalidParamswith typeddata? This SEP requests five general-purpose codes. The core protocol has moved the other way for one case: resource-not-found (-32002) was replaced by-32602, and the Tasks extension uses-32602for an unknown task ID. The codes here also travel insideterminatedsignals, where the client branches on them (NotFoundandUnsupportedmean rediscover and resubscribe,Forbiddenmeans stop), which is the argument for keeping them distinct. -
Should stream liveness move to the core protocol? Telling a quiet stream from a dead one is a transport concern that
subscriptions/listenand other long-lived requests share. If the core protocol defines a keepalive with interval negotiation, this extension would defer to it for liveness and keepnotifications/events/heartbeatonly to advance the cursor during quiet periods, which needs far less frequent messages.
Appendix A: SDK Guidance (non-normative)
Server SDK guidance
A server SDK should make implementing events as simple as implementing tools. The server author writes one function, which checks for changes since a cursor, and the SDK handles delivery mechanics for all three modes. The same check function backs every delivery mode. The SDK decides how to deliver based on what the client requested. By default the server author does not declare which delivery modes an event type supports. The SDK infers them from the server’s configuration and transport:- Poll is backed by the check function when one is provided, and otherwise by the SDK’s emit-fed ring buffer (see Emit-only event types below). The SDK SHOULD enable poll by default, so that it is available unless the author opts out.
- Push is available when the transport supports streaming (Streamable HTTP or stdio).
- Webhook is available when the server has
webhook_ttlconfigured.
delivery array in events/list responses from the above, minus any modes the author has explicitly disabled. Servers that call server.emit() for an event type additionally enable real-time push and webhook delivery without the SDK running an internal polling loop.
events/poll request and returns the result. The server is stateless.
Push mode. The SDK supports two patterns:
- Poll-driven push (default). The SDK maintains an internal polling loop per push subscription, calls the check function periodically, and writes events to the stream. This is the simplest path for servers that wrap poll-only APIs, such as Gmail’s history endpoint.
- Direct emit. Servers with true push sources (webhooks, WebSocket listeners, change streams) emit events directly with
server.emit(). The SDK routes emitted events to all active push streams with matching subscriptions.
events/stream request. When it closes, all loops and listeners stop.
Webhook mode. The SDK uses the same two patterns, poll-driven or direct emit, but POSTs events to the subscriber’s callback URL with HMAC signatures in place of writing to a stream. The SDK holds webhook subscriptions with a TTL per subscription, granted within the server’s configured cap. When the granted TTLs are short, in-memory state is sufficient and no external storage is required. If the server restarts, all webhook subscriptions are lost, and clients resubscribe on their next refresh cycle and pass their last persisted cursor. For event types backed by a durable upstream this resumes without gaps. Emit-only event types lose the events that occurred during the outage. This is the deliberate trade: a short TTL plus refresh substitutes for durable subscription storage. A server configured to grant long or no-expiry TTLs MUST instead persist subscriptions for the lifetime it grants, and SDKs SHOULD refuse a no-expiry cap unless the author has wired up durable storage.
server.emit() is called, the SDK routes the event to all active subscriptions with a matching event name. The SDK supports two emit patterns:
-
Broadcast emit. The server emits an event without specifying a subscription. The SDK fans out per active subscription for that event name, using two hooks that the author supplies:
match(ctx, event, arguments) -> booldecides whether the subscription receives the event. If it is absent, all subscriptions for that event name receive it.transform(ctx, event, arguments) -> eventshapes the payload for that subscription, for example to applyredact_pii, or to expand or thin the payload per a subscriber’sexpandargument. If it is absent, the event is delivered as emitted.
ctxcarries the subscription’s principal and request metadata. Argument semantics are defined by the author (filters, globs, transforms), so the SDK cannot evaluate them generically. These hooks let the author own both filtering and shaping. The SDK applies the same hooks when anevents/pollrequest reads from the emit-only ring buffer, so poll subscribers see the same filtering and shaping as push and webhook subscribers. This pattern fits upstream sources that deliver all events regardless of subscription arguments. An example is a PagerDuty webhook that fires for every incident:matchfilters byseverity, andtransformredacts fields per subscriber. - Targeted emit. The server emits an event to a specific subscription by ID. This is appropriate when the server has set up an upstream listener per subscription and already knows which subscription the event belongs to.
emit_only=True and omits the check function:
events/poll for an emit-only event type reads from this buffer. The cursor is a buffer-local sequence number and is scoped to the process. A server restart invalidates all cursors, and clients receive truncated: true with a fresh cursor. Events emitted during server downtime cannot be recovered. This matches the upstream’s own guarantees for push-only sources, and keeps the author’s implementation to a single emit() call per upstream event.
historyId, Kubernetes resourceVersion, Stripe /v1/events, a Kafka offset), authors SHOULD prefer a check function that queries the upstream directly. The MCP cursor is then the upstream cursor, and poll survives a server restart without gaps.
Subscription lifecycle hooks. For events where the upstream source has to be configured per subscription, such as “watch this Slack channel”, the server needs to know when subscriptions are added and removed. The SDK provides lifecycle hooks:
ResourceExhausted) before they invoke on_subscribe, so that a rejected subscription never provisions upstream resources.
Unsubscribe timing by mode. Push and webhook have explicit end-of-life signals. Push fires on_unsubscribe when the stream closes, and webhook fires it when events/unsubscribe is called or the TTL lapses. Poll does not have one: the client simply stops calling events/poll, and the server never sees a goodbye. To prevent upstream resources that were provisioned for poll from leaking, the SDK treats poll subscriptions as leased. The lease is keyed on (principal-or-null, eventName, canonicalHash(arguments)). On unauthenticated servers, all callers share one lease per (name, arguments). on_subscribe fires the first time a given key appears in a poll request, each later poll for that key renews the lease, and on_unsubscribe fires when the lease expires without renewal. The lease table is ephemeral SDK state and not protocol state. It is never persisted, and a server restart simply fires on_subscribe again on the next poll. The lease window is configurable in the SDK, and SHOULD default to a small multiple of the server’s typical nextPollMs, so that a well-behaved client never lapses between polls:
on_subscribe fires again, which is the correct behavior, because the upstream listener also needs to be established again. Server authors SHOULD write on_subscribe to be idempotent for this reason.
Client SDK guidance
Event names and arguments are not known at code time. They are discovered at runtime throughevents/list, typically driven by the LLM. The client SDK provides a dynamic subscription API:
eventId, gap and truncated handling, and reconnection, all transparently.
Delivery mode selection
The SDK intersects the event type’s advertiseddelivery list with the modes the client is configured to use, and picks in this order of preference:
- Webhook, if the client has
WebhookConfigset and the server lists it. It has low latency and does not tie up a persistent connection. - Push, if the transport supports streaming (stdio, or HTTP when webhook is not configured) and the server lists it. It has low latency but requires holding a connection open.
- Poll, which needs no server state and no persistent connection.
NoCompatibleDeliveryMode. The caller can override the choice per subscription:
How each mode works
Poll mode. The SDK runs a background loop per subscription that callsevents/poll at the interval the server recommends, clamped to a configurable floor (default 1000 ms). Events are yielded to the subscription’s async iterator. The caller does not implement or manage the polling loop.
Push mode. The SDK opens one events/stream per subscription and listens for notifications, routing them by _meta["io.modelcontextprotocol/subscriptionId"]. Adding a subscription opens a new stream, and removing one cancels its stream. On HTTP/1.1 each stream is a TCP connection, so SDKs SHOULD prefer HTTP/2 when many subscriptions are active.
Webhook mode. The SDK generates a whsec_ secret, registers it (or its derivation input) with the gateway, and then calls events/subscribe with delivery: {url, secret}. The response provides the server-derived id for routing. The SDK runs a background refresh loop that calls events/subscribe again before refreshBefore. For a no-expiry grant, the loop drops to an occasional health-check cadence. The SDK monitors deliveryStatus on each refresh to detect delivery failures. The webhook receiver, which may be a forward proxy, accepts incoming POSTs, looks up the secret by X-MCP-Subscription-Id, verifies the Standard Webhooks signature, checks timestamp freshness, and routes events to the right subscription iterator. A verification envelope on a first subscribe names an id the receiver has not seen, so for that envelope it tries the registered secrets that have no id yet, echoes the challenge if one verifies, and binds the id to that secret. It does not pass the envelope on to the SDK. On sub.cancel(), the SDK calls events/unsubscribe for eager cleanup.
Delivering events to the model
When an event arrives, by any delivery mode, the client SDK surfaces it to the agent runtime. How this works depends on the agent framework. It might inject the event into the conversation context, trigger a new agent turn, or queue the event for processing. This extension does not prescribe it. It is an application-level concern.Appendix B: End-to-End Example, a GitHub MCP Server with Webhook Delivery
This walks one concrete topology from the upstream source to the agent’s reaction, using webhook delivery through a forward proxy. The MCP server wraps the GitHub API. It receives pull request activity from GitHub through GitHub’s native repository webhooks, which is the upstream channel and is outside this extension, and delivers it to a forward proxy through an MCP webhook (events/subscribe). The proxy buffers events and serves them to the client over poll or push. When an event arrives, the client SDK wakes the LLM agent.
The Redis lane is illustrative and not normative. In-memory state with a TTL is sufficient for a single-process server. A horizontally scaled server, with several replicas behind a load balancer, needs shared state, so that any replica can match an incoming upstream event to subscriptions created on another replica. Redis with key TTL is the obvious fit, but any shared store with expiry works. The extension does not require this state to be durable when the granted TTLs are short, as in this example. If it is lost, clients create it again on their next refresh, and the client’s persisted cursor covers the gap for event types backed by a durable upstream. A server that grants no-expiry subscriptions would need this state to be durable (see Subscription TTL).
There are two webhook hops here, and they are unrelated. GitHub to the MCP server (step 5) is GitHub’s native webhook product, configured on the server side and outside this extension. The MCP server to the forward proxy (step 8) is the MCP events/subscribe webhook defined above.
Substituting other delivery modes. Only the Subscribe and Event fires boxes change. The upstream leg, GitHub to the MCP server, is identical in all three modes.
- Push. Step 1 becomes
events/stream. Drop the forward proxy lane and the Keepalive box. Steps 8 to 10 collapse into a singlenotifications/events/eventfrom the server to the SDK (see Push-Based Delivery). - Poll. Drop step 1 and the forward proxy lane. The SDK loops
events/pollwith the subscription inline, and steps 8 to 10 become the poll response (see Poll-Based Delivery).