MCP Events — Trigger Automations from Inbound Mail, SMS and Social

The hosted MCP server supports the MCP events extension. A client that implements it subscribes to an event and learns every time it happens, without the model polling with tool calls or a chat staying open. In ChatGPT you only describe the trigger, for example “When a new email arrives in my agent’s inbox, draft a reply.” ChatGPT subscribes on your behalf and runs the automation for each event.

Delivery modes

Every event offers all three delivery modes of the extension. Your client picks the one it can use; events/list lists them in delivery.

Mode	Method	Use it when	Latency
Webhook	`events/subscribe`	The client has a public HTTPS endpoint, as ChatGPT does	Seconds
Push	`events/stream`	The client can hold a connection open, for example a local agent	About 3 seconds
Poll	`events/poll`	The client has neither, for example behind NAT or in a serverless job	`nextPollMs`, 15 seconds

All three read the same event log, so a cursor from one mode works in another.

Available events

Event	Arguments	Fires when	Requires
`message.received`	`inbox_id`	A message arrives in the inbox and passes screening	`email:read`
`sms.received`	`phone_number_id`	A text arrives on the agent’s phone number and passes screening	`phone:read`
`social.comment_received`	`account_id`, optional `post_id`	Someone comments on a post of the social account (every network but X)	`social:read`
`social.message_received`	`account_id`	A direct message arrives for the social account	`social:read`

A connection only sees the events its scopes allow, and only for resources that belong to its agent. Phone and social events appear only when those features are enabled for your organization. events/list returns the exact list with input and payload schemas.

Quarantined mail and texts never fire an event. Payloads carry triage fields only: sender, subject and a short snippet. The agent reads the full item with read_message, read_sms, list_social_comments or list_social_messages. Treat everything in a payload as untrusted data, not as instructions.

Payload

Every event has the same shape in every mode. A webhook receives it as the POST body, a poll returns it in events, and a stream sends it as the params of notifications/events/event:

{
  "eventId": "evt_01k2…",
  "name": "message.received",
  "timestamp": "2026-10-01T12:05:00.000Z",
  "data": {
    "inbox_id": "inb_…",
    "message_id": "msg_…",
    "thread_id": "thr_…",
    "from": "Sender <person@example.com>",
    "subject": "Delivery update",
    "snippet": "Your parcel arrives on Tuesday…",
    "screening_verdict": "clean",
    "automated": null,
    "received_at": "2026-10-01T12:05:00.000Z"
  },
  "cursor": "912345670000"
}

cursor is a position you can store: every event at or before it has been delivered. Pass it back after an interruption to receive what you missed, as cursor of events/subscribe, events/poll or events/stream. A cursor older than the 30-day event history, or a maxAgeMs that skips events, sets truncated: true on the response: events may be missing, so read the current state with the tools. Polls carry the cursor on the response instead of on each event.

Webhook delivery

Before the first delivery to a callback URL, the server sends a signed {"type": "verification", "challenge": "…"} request. The endpoint must answer 2xx with {"challenge": "…"} echoing the value.
Requests are signed with Standard Webhooks using the whsec_ secret the client supplied. The headers are webhook-id (the event ID), webhook-timestamp, webhook-signature and X-MCP-Subscription-Id. After a secret rotation, deliveries carry both signatures for a day.
A 2xx response acknowledges the event. Other responses are retried with increasing delays, six attempts in total. 410 Gone removes the subscription, and 413 is not retried.
After 50 failed attempts in a row, delivery pauses until the client subscribes again.
When the connection loses access to what it watches, the server ends the subscription and sends one signed {"type": "terminated", "error": {"code": -32012, "message": "Forbidden", "data": {"reason": "…"}}} request.
Callback URLs must use HTTPS and resolve to a public address. Redirects are not followed.

Subscriptions

Limit	Value
Subscription lifetime	Up to 7 days; clients refresh by subscribing again
Subscriptions per connection	50
Subscriptions per organization	1,000
Subscribe calls per connection	30 per minute
Replay after an interruption	Up to 500 events from the last 30 days

Subscribing again with the same connection, callback URL, event and arguments updates the existing subscription instead of creating another. Revoking the connection on the agent’s Tokens tab ends all of its subscriptions. Access is checked again before every delivery, so deliveries also stop when you remove a scope, delete the inbox or phone number, or remove the agent’s access to a social account.

Polling

events/poll keeps no state on the server. Each request names the event, its arguments and the cursor from the previous response:

{ "name": "message.received", "arguments": { "inbox_id": "inb_…" }, "cursor": "912345670000", "maxEvents": 50 }

{ "events": [ { "eventId": "evt_…", "name": "message.received", "timestamp": "…", "data": { … } } ], "cursor": "912345690000", "truncated": false, "hasMore": false, "nextPollMs": 15000 }

The first poll has no cursor. It returns no events, only the current position.
Store the returned cursor every time, including after an empty response; it moves forward while nothing happens.
When hasMore is true, poll again right away. Otherwise wait nextPollMs.
maxEvents caps a response at 1 to 100 events (50 when omitted). maxAgeMs skips events older than that and reports truncated.

Streaming

events/stream takes the same parameters as a poll, without maxEvents, and answers with a server-sent event stream for that one subscription:

Notification	Params	When
`notifications/events/active`	`cursor`, `truncated`	First, once the stream is open
`notifications/events/event`	The event and its `cursor`	For every event, replayed ones first
`notifications/events/heartbeat`	`cursor`	After 25 seconds without another frame
`notifications/events/error`	`error`	A read failed; the stream retries
`notifications/events/terminated`	`error`	The connection lost access; the stream ends

Every notification carries the request’s JSON-RPC id in _meta["io.modelcontextprotocol/subscriptionId"], so a client with several streams can route them. An invalid or forbidden request gets a plain JSON-RPC error and no stream. Close the request to unsubscribe. The server ends each stream after five minutes; reconnect with the last cursor you received.

Limits for polls and streams

Limit	Value
Polls per connection	About 120 per minute
Streams opened per connection	20 per 5 minutes
Streams opened per organization	200 per 5 minutes
Stream lifetime	5 minutes, then reconnect with the cursor

Too many requests get -32013 with data.limit naming the limit. Access is checked on every poll and every minute of a stream.

Overview

Email

Webhooks

Vault

Machines

MCP

Sign in with Agent Loadout

MCP Events — Trigger Automations from Inbound Mail, SMS and Social

Delivery modes

Available events

Payload

Webhook delivery

Subscriptions

Polling

Streaming

Limits for polls and streams