> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agent-loadout.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Subscribe MCP clients such as ChatGPT to Agent Loadout events. Inbound mail, texts and social comments arrive as signed webhooks that start automations.

The hosted MCP server supports the MCP events extension. A client that implements it, such as ChatGPT automations, subscribes to an event once and receives a signed webhook every time it happens. You don't need to poll or keep a chat 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.

## 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.

<Warning>
  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.
</Warning>

## Payload

Every delivery is a POST with a JSON body:

```json theme={null}
{
  "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",
    "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 to `events/subscribe` after an interruption to receive what you missed.

## Delivery and signing

* 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](https://www.standardwebhooks.com/) 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.
* 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.