# MCP Events

Source: https://tpiros.dev/blog/mcp-events

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](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/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

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.

```json
{
  "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.

```json
{
  "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.

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.

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.

```json
{
  "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.

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](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md)), 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.

```http
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.

```ts
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

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.

```ts
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.

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.

```ts
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](https://developers.openai.com/plugins/build/mcp-events) 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](https://vercel.com/changelog/vercel-mcp-now-supports-mcp-events) 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](/ai-engineering-for-web-developers/mcp/) builds a server and a client in TypeScript, the request and response half that Events adds to.
