Skip to main content
The AGO MCP server supports the MCP Events extension (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.
Events work with the same API key or OAuth token as the tools. You can receive an event if your key has the scope listed for it below: a key that can read tickets can receive ticket events.

Discover events

The initialize response lists the extension under capabilities.extensions. Call events/list to get the events your key can receive. Each entry has:

Poll events

Send events/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: true means more events are waiting: poll again right away with the new cursor.
  • nextPollMs is the suggested wait before the next poll when hasMore is false.
  • truncated: true means some events could not be returned: your cursor was older than 14 days, or than maxAgeMs. Read the current state of the objects you track with the tools, then keep polling with the new cursor.
  • eventId identifies the event. You may receive the same event again, for example after a retry: ignore an eventId you already handled.

Receive events by webhook

Send events/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:
Your endpoint must answer 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 a POST with a JSON body:
Deliveries follow the Standard Webhooks signature scheme, so its libraries can check them. Each request carries: 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 than maxAgeMs. 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.
To change the secret, subscribe again with the new one: for 24 hours, deliveries are signed with both.

Failures and retries

Events are delivered one at a time, in order. When your endpoint fails, times out or answers with another status than 2xx, 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

Send events/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:
Keep the latest 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