io.modelcontextprotocol/events). An agent or integration connected to /api/v1/mcp learns what happened in your workspace, such as a ticket created, a conversation handed to a human or a knowledge gap detected, and acts on it with the MCP tools without a user in the loop. It can receive events three ways:
- Poll: ask AGO what happened since its last check with
events/poll. - Stream: keep a connection open with
events/stream, and AGO pushes each event on it as it happens. - Webhook: subscribe once with
events/subscribe, and AGO sends each event to your HTTPS endpoint as it happens.
Discover events
Theinitialize response lists the extension under capabilities.extensions. Call events/list to get the events your key can receive. Each entry has:
Poll events
Sendevents/poll with one event name. The first call passes cursor: null: it returns no events and a cursor that marks the current time. Each following call passes the cursor of the previous response and returns the events that happened since.
In the response:
hasMore: truemeans more events are waiting: poll again right away with the new cursor.nextPollMsis the suggested wait before the next poll whenhasMoreis false.truncated: truemeans some events could not be returned: your cursor was older than 14 days, or thanmaxAgeMs. Read the current state of the objects you track with the tools, then keep polling with the new cursor.eventIdidentifies the event. You may receive the same event again, for example after a retry: ignore aneventIdyou already handled.
Receive events by webhook
Sendevents/subscribe with one event name, optional filters and your endpoint. AGO then posts every matching event to the endpoint, in order, about 10 seconds after it happens.
A subscription is identified by your key, the event name, the filters and the URL. Calling
events/subscribe again with the same values refreshes it: send it before refreshBefore to keep receiving events, otherwise the subscription is deleted. A refresh keeps the position reached, so no event is missed or sent twice. Each key can hold 50 subscriptions.
To stop, send events/unsubscribe with the same name, arguments and delivery.url.
Verify your endpoint
The first time a key subscribes an endpoint, AGO sends it a challenge:200 with the same challenge, { "challenge": "Gb97J-JLwppqwbqNXwhrdSRyJHgqFhjI" }. Otherwise events/subscribe fails with -32027 and data.reason saying why: challenge_failed, connection_refused, timeout or tls_error.
Handle deliveries
Each event arrives as aPOST with a JSON body:
Answer with a
2xx status within 5 seconds, and do the work afterwards. AGO also sends:
{ "type": "gap", "cursor": "..." }when events could not be delivered because they are older than 14 days or thanmaxAgeMs. Read the current state of the objects you track with the tools.{ "type": "terminated", "error": { "code": -32024, "message": "Access revoked" } }when your key is revoked or loses the scope the event requires. The subscription is deleted.
Failures and retries
Events are delivered one at a time, in order. When your endpoint fails, times out or answers with another status than2xx, AGO retries the same message after 5 seconds, 30 seconds, 2 minutes, 5 minutes, 15 minutes and then every 30 minutes, and holds the following events until it succeeds. After an hour of failures, the subscription is suspended: deliveryStatus.active becomes false and lastError and failedSince say what went wrong. Subscribe again once your endpoint is fixed: delivery resumes from the event that failed.
A 410 or 413 answer is not retried: AGO skips that event and moves on.
Stream events
Sendevents/stream to keep a connection open and receive each event as it happens, without a public endpoint. AGO answers with a stream of server-sent events (text/event-stream), so send Accept: application/json, text/event-stream.
Each message of the stream is a JSON-RPC notification whose
params._meta["io.modelcontextprotocol/subscriptionId"] is the id of your request:
cursor you received. A stream lasts at most 10 minutes and ends with the response to your request ("resultType": "complete"): open a new one with that cursor to continue without missing events. Do the same if the connection drops. To stop, close the connection.
An invalid request gets a JSON-RPC error instead of a stream.
Limits
- Events are kept for 14 days.
- An event appears in polls, streams and webhook deliveries about 10 seconds after it happens.
- A key can keep 10 streams open at once.
- Event data identifies what happened: call a tool, such as
get_ticket, to read the full object. Treat event data like any tool result: it can contain text written by your customers. - AGO records events for real conversations and tickets only: simulations, personal mailboxes and helpdesk history older than one hour imported by a sync are left out.
- Conversations that go quiet and SLA deadlines are only available as workflow triggers, not through MCP Events.
Events
The identifiers in
data are those the tools accept, such as ticket_id for get_ticket and thread_id for get_conversation. A field without a value is an empty string.
Errors
Related
- Webhooks: create webhooks from the admin page or the REST API
- MCP Server
- OAuth Scopes
- Workflows
