MCP Events Implementation Guide for ChatGPT

Implementing MCP Events in ChatGPT requires MCP 2.0 (protocol version 2026-07-28) and outbound HTTPS access to a callback URL. The system uses webhook delivery and callback verification based on the draft MCP Events spec, explicitly excluding polling, streaming, and gap or terminated control notifications.

Protocol and Workflow

The workflow begins when a server advertises event support by adding events: {} to its server/discover capabilities. The server must implement three methods: events/list for available events, events/subscribe for creating subscriptions, and events/unsubscribe for stopping them. ChatGPT initiates a subscription by providing a callback URL and signing secret, after which the server sends matching events to that URL.

Subscription and Verification

Subscriptions are created via events/subscribe, requiring a signing secret with a whsec_ prefix (24–64 bytes when base64 decoded). Before sending data, the server must verify the callback URL using a signed request containing a single-use challenge. Verification requires a 2xx response and constant-time comparison of the echoed challenge. Failed verification returns JSON-RPC error -32015.

Event Delivery and Security

Events are delivered via POST requests with headers including webhook-id, webhook-timestamp, and webhook-signature using the Standard Webhooks HMAC method. The payload must not exceed 256 KiB and should avoid including model behavioral instructions. Delivery responses of 410 or 413 prohibit retries, while transient failures use exponential backoff. Write tools must be idempotent to handle potential out-of-order or duplicate deliveries.

Subscription Management

Subscriptions are idempotent and must persist across server restarts. ChatGPT refreshes subscriptions before the refreshBefore date, supporting optional ttlMs for custom lifetimes. Replayable events use cursors to resume delivery, while non-replayable types return cursor: null. Unsubscribing requires matching the original event name, arguments, and callback URL.