MCP Events Explained: Webhooks, Push and Polling for Agents, and What to Check Before Subscribing

Until now an MCP server could only answer when an agent asked. MCP Events is a draft extension that lets a server tell the agent when something happens: a new order, a failed build, an incident opened. It is being developed by the MCP Triggers and Events working group in the experimental-ext-triggers-events repository, and it is explicitly experimental: the repository states that its contents do not represent official MCP specifications. ChatGPT has been reported to support the proposal at protocol version 2026-07-28, so servers that implement it are starting to appear.

An event feed is also a new path from a third party into an agent's context. That is the reason to read the design before connecting to one. This post summarizes what the draft defines, then lists what can be checked from the outside.

What the draft defines

A server advertises the capability as capabilities.events. Four methods sit on the same endpoint as tools/list:

Method	Purpose
events/list	Returns the event types the server can emit
events/poll	Client asks for events since a cursor
events/stream	Long-lived request; events arrive as SSE messages (or stdio notifications)
events/subscribe / events/unsubscribe	Register or remove a webhook callback

Each event type descriptor carries a name, a description, a delivery array that is a subset of poll, push and webhook, an inputSchema for subscription arguments and a payloadSchema for the event data. An actual occurrence has an eventId for deduplication, a timestamp, the payload, and an optional cursor for replay.

The three delivery modes

• Poll is stateless. The client sends a cursor and gets back events, a new cursor and a nextPollMs hint.
• Push keeps one events/stream request open per subscription. The server sends a heartbeat at least every 30 seconds carrying the current cursor.
• Webhook is the one with the most moving parts. The client calls events/subscribe with a callback URL and a secret it generated (whsec_ followed by base64 of 24 to 64 random bytes). The server returns a subscription id and a refreshBefore time; the client must refresh before then, or the subscription lapses.

How webhook delivery is secured

The draft borrows the Standard Webhooks profile. Every delivery carries webhook-id, webhook-timestamp and webhook-signature, where the signature is v1, plus the base64 HMAC-SHA256 of id.timestamp.body using the subscriber's secret. Receivers verify over the raw body bytes, reject timestamps older than five minutes and deduplicate on webhook-id.

Before a server sends real data to a new callback, it POSTs a verification envelope containing a nonce, and the endpoint must echo that nonce in a 2xx response. Callback URLs must be https://. The server must validate the destination IP at delivery time against the IANA special-purpose registries, connect to the validated address, and refuse redirects. That is the draft's answer to server-side request forgery: a subscription API is a way to make a server send HTTP requests to an address you choose.

The draft also requires a caller identity. A subscription is keyed on principal, callback URL, event name and arguments, so a server with no authentication cannot offer webhook mode. New JSON-RPC codes -32023 to -32027 cover not found, forbidden, resource exhausted, unsupported, and callback endpoint failure.

What to check before an agent subscribes

Most of this can be read from events/list without receiving a single event.

1. Are the descriptions safe to hand to a model? An agent decides whether to subscribe from the event's description. Zero-width characters, "ignore previous instructions" phrasing and hidden <important> blocks belong in the same review as tool descriptions.
2. Is there a payloadSchema? It is the contract for what will land in the agent's context. An event with no schema, or one whose type is not object, cannot be validated by the consumer.
3. Do the delivery modes make sense? An event with no delivery entry, or one with a mode outside poll, push and webhook, is a server that has not followed the draft.
4. Does a server with no authentication offer webhook delivery? The draft says that combination is not allowed. Either the server is not implementing the draft as written or the subscription is not tied to an identity.
5. Does it refuse bad callbacks? A compliant server rejects http:// callbacks and loopback or private addresses, or fails the verification challenge. One that accepts them without a challenge has skipped the draft's main safeguard.
6. Will you notice when the definition changes? The set of events, their descriptions and especially their payloadSchema can change under a client that subscribed last month. Pin them, and compare on every scan.

Doing it from the outside

The ContextIQ MCP Inspector runs these checks on any public server URL. When server/discover reports the events capability, the scan calls events/list, shows each event with its delivery modes and schemas, and lints the catalog against the rules above. Each event definition is pinned, so a later scan of the same server reports which event changed and which part of it (description, schema or delivery modes).

For servers that answer without authentication and offer a webhook event that needs no arguments, the scan also sends two events/subscribe requests whose callbacks cannot deliver anywhere: a plain http:// address on the reserved .invalid domain, and https://127.0.0.1:9. A refusal is recorded as a pass. An acceptance is flagged and the scan unsubscribes immediately. Anything else, such as a login wall or an unrelated error, is reported as inconclusive rather than as a pass, because the draft's wire format may still change.

The scan never opens events/stream and never calls events/poll, since both return real event data. It cannot verify replay behavior, heartbeat timing or signature correctness, and it is not a conformance test for a draft that has no conformance suite.

Where this is going

If Events becomes part of the core specification, expect the details above (method names, the delivery object, error codes) to shift. The shape is unlikely to: servers push, agents react, and the callback is the attack surface. Reviewing the catalog and the callback rules now is cheaper than doing it after an agent has been wired to a feed.