io.modelcontextprotocol/events). SEP-3415 is
Final, and the extension is in Beta. The
Tasks and Events Working Group
maintains it.
modelcontextprotocol/ext-events
Full specification and documentation for MCP Events.
Why not existing notifications?
MCP already has notifications such asnotifications/resources/updated and the
list_changed family. They don’t cover this use case:
- No parameters or payload. A notification says that a URI or a list changed. It can’t express “a P1 incident was created for service X”, because there are no subscription arguments, no payload schema and no payload.
- A live connection is required. Notifications arrive only on an open
subscriptions/listenstream. A client that isn’t connected receives nothing. - No resumption. There is no cursor, so anything that happens during a disconnect is lost, and the client can’t tell that it missed anything.
How Events work
-
Capability negotiation. The server advertises
io.modelcontextprotocol/eventsin itsserver/discovercapabilities. The client may declare the same identifier in its per-request capabilities. -
Discovery. The client calls
events/list. Each event type has aname, aninputSchemafor subscription arguments, apayloadSchemafor the data it delivers, and thedeliverymodes it supports. -
Subscription. The client subscribes with an event name and arguments,
using one of the modes the event type lists. A
nullcursor means “start from now”. -
Delivery. Each event arrives as an occurrence:
{eventId, name, timestamp, data, cursor}. The client stores the cursor after each delivery. -
Resumption. After a disconnect or a restart, the client resubscribes
with its stored cursor. If the server can’t serve from that position, it
says so with
truncated: true, so the client knows that events were skipped. - Reaction. The client SDK hands each event to the agent runtime, which decides how to react, for example by starting a new agent turn.
Delivery modes
None of the three modes is mandatory. An event type lists any non-empty subset of them, and the client SDK picks one it can use.
SDKs typically prefer webhook when the client has a callback endpoint, then
push, then poll. A client can override the choice per subscription.
When to use Events
Events are a good fit when your use case involves: Reacting to upstream activity. New messages, repository pushes, payments, incidents or calendar changes that an agent should act on. Unattended agents. Background agents that run when no user is present and need to be woken by something happening. Filtered streams. Subscriptions that narrow a large stream with arguments, such as “P1 incidents for service X” or “email from this sender”. If the client is waiting for the result of a long-running operation it started itself, use Tasks instead.Cursors and delivery guarantees
Cursors are opaque, server-defined positions in the event stream. They make delivery at-least-once when the upstream is durable and the client resumes from its last cursor.- Replay is optional per event type. A server returns
cursor: nullfor an event type that has no addressable history. The client then always starts from now, and accepts that events during a gap can’t be recovered. - Bounded replay. A client can pass
maxAgeMswith a stale cursor, so that a host that was offline for a week gets at most, say, the last five minutes. - Deduplication.
eventIdis stable for an upstream event, so a client can discard duplicates within a subscription. - Ordering. Poll and push deliver events in order within a subscription.
Webhook ordering is best-effort, and the
timestampfield orders events.
Security model
- Payloads are untrusted data. Event payloads come from external systems and can carry prompt injection. Treat them like tool results, and sanitize or sandbox them before they reach a model.
- Minimal payloads. Servers should send enough to identify and triage an event, such as a sender, subject and ID, and let the client fetch full content with tools.
- Authorization at every step. The server checks permission at subscribe time, re-checks at delivery time, and terminates the subscription if access is revoked. Receiving an event never authorizes the agent to act: its follow-up tool calls go through normal MCP authorization.
- Webhook hardening. Deliveries are signed with
Standard Webhooks HMAC signatures.
Callback URLs must be
https, the server verifies an endpoint before it delivers to it, and it validates destination IPs to prevent SSRF.
Implementation guide
For MCP clients
1
Declare support
Include the extension in the per-request capabilities you send:Don’t send
events/* requests to a server that hasn’t advertised the extension.2
Discover and subscribe
Call
events/list, validate subscription arguments against each event type’s
inputSchema, and pick a delivery mode from its delivery list.3
Persist cursors
Store the latest cursor for each subscription durably, and resume from it after
a restart. Treat
truncated: true as a possible gap, and re-read authoritative
state with tools if it matters.4
Deliver events safely
Deduplicate by
eventId, and treat payloads as untrusted before passing them
to a model.For MCP servers
1
Advertise support
Include the extension in your
server/discover capabilities. Set listChanged
if you send notifications/events/list_changed:2
Describe event types
Return each event type from
events/list with its inputSchema,
payloadSchema and supported delivery modes. Evolve schemas additively, and
publish a breaking change under a new event name.3
Use upstream identifiers
Use the upstream system’s stable event ID as
eventId, and encode the upstream
position in the cursor, so that clients can resume and deduplicate.4
Check authorization
Verify that the principal may subscribe with the given arguments, and terminate
subscriptions when access is revoked.
Client support
MCP Events is an extension to the core MCP specification.
It requires protocol revision
2026-07-28 or later.