MCP Events
An MCP server only answers when asked. MCP Events is a draft extension that lets it tell an agent something happened, by poll, push or webhook. Try all 3 here.
An MCP server never speaks first.
An agent connects, asks which tools exist, calls one and gets an answer back. That works while somebody is sitting there typing. It stops working at 03:00, when the airline cancels your 07:10 flight and you’re asleep.
MCP Events is a proposed fix. It’s a draft extension to MCP (SEP-3415, from the Triggers & Events Working Group) that lets a server tell an agent that something happened. ChatGPT and Vercel’s MCP server already ship part of it.
I built a small demo of it around a made-up airline’s flight status feed. The widgets in this post replay what it puts on the wire, and the code samples are trimmed from it.
MCP only answers when asked
MCP today
tools/call get_flight →
← NV318, on time
The agent asks and the server answers. If the flight is cancelled at 03:00, nothing happens until somebody asks again.
With Events
subscribe to flight.changed →
← flight.changed NV318
The agent host subscribes once. When the flight changes, the server says so, and the model starts work.
Today an agent that wants to know whether your flight is still on time has to call a tool again and again and compare the answers itself.
MCP does have notifications already. They can say “this resource changed” or “this list changed”. They carry no details, you can’t filter them, and they only arrive while a connection is open.
An event is a small, typed message
Events gives a server one more thing to offer next to its tools, a list of event types. A client calls events/list to read it. This is one entry from my demo, trimmed to keep it short.
{
"name": "flight.changed",
"description": "Fires when a flight is delayed, moves gate or is cancelled",
"delivery": ["poll", "push", "webhook"],
"inputSchema": {
"type": "object",
"properties": {
"flight": { "type": "string" },
"kind": { "type": "string", "enum": ["delay", "gate", "cancelled"] }
}
}
}
inputSchema is the filter. Subscribe with { "flight": "NV318" } and you only hear about your own flight. delivery lists the ways this server is willing to send the event.
When something happens to that flight, every delivery mode hands over the same object.
{
"eventId": "C-1042",
"name": "flight.changed",
"timestamp": "2026-11-11T03:00:12Z",
"data": {
"flight": "NV318",
"kind": "cancelled",
"detail": "Cancelled, crew out of hours"
},
"cursor": "42"
}
The payload is small on purpose. It says which flight and what happened, and the agent calls the get_flight tool for the rest, such as the next departure it could rebook you onto. (I’ll come back to cursor.)
Somebody typed that detail text, and it’s about to land in front of a model that can rebook flights with your card. The SEP calls event payloads “untrusted data, like tool results”, and that’s how I’d handle them.
When a flight is cancelled, everyone on it wants a seat on the next one. The agent that hears first rebooks first, so how the news travels matters. The proposal has 3 ways to send it.
Poll, where the agent keeps asking
The first way barely changes anything. The agent host (the program that runs the model, ChatGPT or your own script) calls events/poll on a timer, and the server replies with whatever is new.
Press Cancel a flight and watch how long the news sits on the server.
Poll delivery
One events/poll request every 6 seconds.
Agent host
the MCP client
model idle
MCP
MCP server
an airline's flight status
waiting none
- Requests sent
- 0
- Came back empty
- 0
- Sat on the server
- –
Waiting for the first poll…
Most of those requests came back with 0 events. That’s the normal case for polling. The cancellation had to wait for the next request, which is up to 6 seconds here. The server sets that gap itself with nextPollMs, and the SEP’s own example asks for 30 seconds.
Poll has one big thing going for it, which is that it works everywhere. The server keeps no memory of who is polling. The agent host needs no public address, so it can run on a laptop behind a home router.
Push, where the line stays open
The second way is one request that never finishes. The agent host sends events/stream, the server confirms with active, and from then on it sends each event the moment it happens.
Push delivery
A single events/stream request. The server answers whenever it has something.
Agent host
the MCP client
model idle
MCP
MCP server
an airline's flight status
waiting none
- Requests sent
- 0
- Stream open for
- –
- Sat on the server
- –
Opening the stream…
This time the news didn’t sit on the server at all. It left the moment the flight was cancelled, and the request count stayed at 1.
The heartbeat messages are the server saying “still here”. Without them, a quiet stream and a dead connection look the same from the agent’s side. The SEP asks for one at least every 30 seconds (my demo sends one every 10, and so does the widget).
You pay for that with an open line. The server holds one long-lived request per subscription, and the agent host has to stay up to hold its end.
Webhook, where the server calls back
The third way needs no connection at all. The agent host calls events/subscribe once and hands over 2 things, a URL and a secret.
{
"method": "events/subscribe",
"params": {
"name": "flight.changed",
"arguments": { "flight": "NV318" },
"delivery": {
"mode": "webhook",
"url": "https://agent.example.com/hooks/8f2c",
"secret": "whsec_..."
},
"ttlMs": 60000
}
}
After that the server sends an HTTPS POST to that URL for every event.
Webhook delivery
One events/subscribe request, then signed HTTPS POSTs to the callback URL.
Agent host
has a public HTTPS URL
model idle
MCP
HTTPS to the callback URL
MCP server
an airline's flight status
waiting none
no subscription yet
- MCP requests
- 0
- Connections held
- 0
- Sat on the server
- –
Subscribing…
A few things happened there that the other 2 modes don’t need.
The server sent a challenge to the URL and waited for the echo before it delivered anything. Skip that step and anyone could point your server at somebody else’s address and have it flooded with POSTs.
Each POST is signed with the secret (the proposal uses Standard Webhooks), so the receiver can check that the event came from the server it subscribed to. The event is the body, and the signature travels in the headers.
POST /hooks/8f2c HTTP/1.1
webhook-id: msg_p9Xw2mVq7LrT4kYs8NbC1g
webhook-timestamp: 1794366012
webhook-signature: v1,P68u6ucoNCXXcTuGzNjpoGlUn+GYJ3Jjm+9NQlHFvCg=
X-MCP-Subscription-Id: sub_57c4019043d5764c
{"eventId":"C-1042","name":"flight.changed", ...}
Checking it takes a few lines. The one thing to get right is hashing the body exactly as it arrived, before anything parses it.
const expected = createHmac('sha256', key)
.update(`${webhookId}.${timestamp}.`)
.update(rawBody)
.digest('base64');
const ok = timingSafeEqual(Buffer.from(expected), Buffer.from(received));
And the subscription expires. The bar under the server is its time to live. The agent host pushes the expiry back by calling events/subscribe again, and if it ever stops doing that, the server cleans up without being told.
Webhooks take more work to build. The agent host needs a public HTTPS address. The server has to send requests to URLs that strangers hand it, and that’s easy to get wrong. My demo checks where a URL points once, when you subscribe. The SEP wants that checked again on every delivery, and I skipped it.
In return nothing has to stay connected. You can switch the model off until a POST arrives.
The same cancellation, 3 ways
One cancellation, 3 deliveries
Agent host on the left, MCP server on the right. All 3 subscriptions are already set up.
Poll
a request every 6s, most of them empty
nothing yet
Push
one connection held open the whole time
nothing yet
Webhook
no connection, but a public URL to call
nothing yet
Push and webhook tie. Poll loses by however long was left on its timer, and with a 30 second timer that could be the last seat on the next flight.
3 modes for one job is a lot. The SEP admits as much and puts the price at “roughly three times the specification and SDK surface”. Its argument is that no single mode works for everyone. A serverless server can’t hold a stream open, and a laptop behind a home router can’t receive a webhook.
So none of the 3 is required. A server offers the ones it can for each event type, and the client picks from that list.
The code that reacts to the event is the same whichever one it picks. This is the loop from my demo’s agent.
const sub = await events.subscribe('flight.changed', { flight: 'NV318' });
for await (const event of sub) {
const flight = JSON.parse(await callTool('get_flight', { flight: event.data.flight }));
if (flight.status === 'cancelled') log(`rebook onto ${flight.nextDeparture}`);
}
(events.subscribe is a small helper I wrote for the demo. It runs the poll timer, holds the stream or renews the webhook, so the loop never has to know.)
Cursors answer “what did I miss?”
Connections drop and laptops close. Say yours stayed shut for a whole flight. When it opens again, the agent host has missed every event the server sent in between, and it needs a way to ask for them.
That’s what the cursor on each event is for. It’s a bookmark. The agent host stores the latest one and sends it back when it reconnects, and the server replays everything after it.
Press Disconnect, change 3 flights, then reconnect.
A cursor is a bookmark
This server keeps its last 6 events. Disconnect, change a few flights, then reconnect.
Events on the MCP server, in order
connected▲ cursor: "3"
Events 1 to 3 were delivered. The agent host's cursor is "3".
Now do it again with 8 changes. This server only keeps its last 6 events, so 2 are gone and the reply says truncated: true. Those 2 are lost, but at least the agent knows there’s a hole.
The server decides what goes inside a cursor. In my demo it’s the change’s sequence number, and a client should still treat it as a string it can’t read.
On the server, all of this comes down to one function per event type. It gets the subscription’s filter and the cursor, and returns what has happened since. This is mine with the edge cases cut.
events.event({
name: 'flight.changed',
check: (args, cursor) => {
const changes = flights
.since(Number(cursor))
.filter((c) => !args.flight || c.flight === args.flight);
return {
events: changes.map((c) => ({
eventId: c.id,
name: 'flight.changed',
timestamp: c.changedAt,
data: { flight: c.flight, kind: c.kind, detail: c.detail },
cursor: String(c.seq),
})),
cursor: String(flights.headSeq()),
};
},
});
The same function answers a poll, feeds an open stream and fills the webhook POSTs. (events.event is my demo’s helper too. No official SDK has one yet, though the SEP’s appendix sketches something close.)
What has shipped
The SEP is still an open draft, and it says itself that the reference implementation in an official SDK is still to come. 2 products went ahead anyway.
OpenAI’s docs describe ChatGPT subscribing to MCP events, and they’re blunt about how much of the draft that covers. “Polling, streaming, and the draft’s gap and terminated control notifications are not supported by this integration.” It’s webhooks only.
Vercel’s MCP server has published events since 30 October. An agent can subscribe to deployment.succeeded and deployment.error and react to a broken deploy, and the deliveries are signed Standard Webhooks.
Both picked webhooks. My guess at why is that a hosted agent isn’t running while you’re away, and a POST is a cheap way to wake it up.
The SEP says the choice of 3 modes “may be revisited if real deployments converge on a subset”. 2 products is a small sample, but if you only have time to learn one mode, I’d make it webhooks.
The book’s MCP chapter builds a server and a client in TypeScript, the request and response half that Events adds to.