> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Events

> Receive AGO events (new tickets, status changes, knowledge gaps) in an MCP client, by polling, streaming or webhook

The AGO MCP server supports the [MCP Events extension](https://modelcontextprotocol.io/extensions/events/overview) (`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](https://ago.mintlify.site/api/mcp-tool-api.md) 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:

| Field | Description |
| - | - |
| `name` | Event name, such as `ticket.created` |
| `description` | When the event happens |
| `delivery` | `["poll", "push", "webhook"]` |
| `inputSchema` | The filters you can pass as `arguments` |
| `payloadSchema` | The fields of each event's `data` |

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

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "events/poll",
  "params": {
    "name": "ticket.priority_changed",
    "arguments": { "priority": "Urgent" },
    "cursor": "WyIyMDI2LTExLTIxVDA4OjU5OjUwKzAwOjAwIiwiZmZmZmZmZmYtZmZmZi1mZmZmLWZmZmYtZmZmZmZmZmZmZmZmIl0"
  }
}
```

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "resultType": "complete",
    "events": [
      {
        "eventId": "3f1d2c8e-5a7b-4c1e-9d2f-8b6a4e0c1f23",
        "name": "ticket.priority_changed",
        "timestamp": "2026-11-21T09:00:12.481000+00:00",
        "data": {
          "ticket_id": "9b0e7f52-1c3d-4e8a-b6f4-2d5c7a9e0b14",
          "priority": "Urgent",
          "previous_priority": "Normal"
        }
      }
    ],
    "cursor": "WyIyMDI2LTExLTIxVDA5OjAwOjEyLjQ4MTAwMCswMDowMCIsIjNmMWQyYzhlLTVhN2ItNGMxZS05ZDJmLThiNmE0ZTBjMWYyMyJd",
    "truncated": false,
    "hasMore": false,
    "nextPollMs": 30000
  }
}
```

| Parameter | Description |
| - | - |
| `name` | The event to poll. One event per request. |
| `arguments` | Optional filters from the event's `inputSchema`. An event is returned only if every filter matches its field. Text values are compared without regard to case. |
| `cursor` | `null` to start from now, or the `cursor` of the previous response. Store it after every poll. |
| `maxEvents` | Optional, 50 by default, at most 200. |
| `maxAgeMs` | Optional. Skip events older than this many milliseconds, for example after a long pause. |

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.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "events/subscribe",
  "params": {
    "name": "ticket.priority_changed",
    "arguments": { "priority": "Urgent" },
    "delivery": {
      "mode": "webhook",
      "url": "https://hooks.example.com/ago",
      "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
    },
    "ttlMs": 86400000
  }
}
```

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "id": "sub_4f5d4b9f30f28e74a31e8f527925f9c7",
    "refreshBefore": "2026-11-22T09:00:00+00:00",
    "cursor": "WyIyMDI2LTExLTIxVDA4OjU5OjUwKzAwOjAwIiwiZmZmZmZmZmYtZmZmZi1mZmZmLWZmZmYtZmZmZmZmZmZmZmZmIl0",
    "truncated": false,
    "deliveryStatus": { "active": true, "lastDeliveryAt": null, "lastError": null }
  }
}
```

| Parameter | Description |
| - | - |
| `name` | The event to receive. One event per subscription. |
| `arguments` | Optional filters, as for polling. |
| `delivery.url` | Your endpoint. It must use HTTPS and be reachable from the internet. |
| `delivery.secret` | The key AGO signs deliveries with: `whsec_` followed by 24 to 64 random bytes in base64. Generate it yourself and keep it secret. |
| `cursor` | Optional. `null` or absent to receive events from now on, or a cursor from a poll or an earlier delivery to also receive what happened since. |
| `maxAgeMs` | Optional. With `cursor`, skip events older than this many milliseconds. |
| `ttlMs` | Optional lifetime in milliseconds, 24 hours by default and at least 5 minutes. With an API key, `null` keeps the subscription until you unsubscribe. With an OAuth token, a subscription lasts at most 24 hours. |

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:

```json theme={null}
{ "type": "verification", "challenge": "Gb97J-JLwppqwbqNXwhrdSRyJHgqFhjI" }
```

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:

```json theme={null}
{
  "eventId": "3f1d2c8e-5a7b-4c1e-9d2f-8b6a4e0c1f23",
  "name": "ticket.priority_changed",
  "timestamp": "2026-11-21T09:00:12.481000+00:00",
  "data": {
    "ticket_id": "9b0e7f52-1c3d-4e8a-b6f4-2d5c7a9e0b14",
    "priority": "Urgent",
    "previous_priority": "Normal"
  },
  "cursor": "WyIyMDI2LTExLTIxVDA5OjAwOjEyLjQ4MTAwMCswMDowMCIsIjNmMWQyYzhlLTVhN2ItNGMxZS05ZDJmLThiNmE0ZTBjMWYyMyJd"
}
```

Deliveries follow the [Standard Webhooks](https://www.standardwebhooks.com/) signature scheme, so its libraries can check them. Each request carries:

| Header | Description |
| - | - |
| `webhook-id` | Message identifier. A retry of the same message keeps it: ignore an id you already handled. |
| `webhook-timestamp` | Unix time of the attempt. Reject requests older than a few minutes. |
| `webhook-signature` | `v1,` followed by the base64 HMAC-SHA256, keyed with the decoded secret, of `webhook-id`, `webhook-timestamp` and the raw body joined by dots. Several signatures separated by spaces follow a secret change: accept the request if one matches. |
| `X-MCP-Subscription-Id` | The subscription's `id`. |

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

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "tickets-stream",
  "method": "events/stream",
  "params": {
    "name": "ticket.created",
    "arguments": { "status_id": "open" },
    "cursor": null,
    "heartbeatMs": 30000
  }
}
```

| Parameter | Description |
| - | - |
| `name` | The event to receive |
| `arguments` | Optional filters, as in `events/poll` |
| `cursor` | `null` to start from now, or the last cursor you received to replay what happened since |
| `maxAgeMs` | Optional: with a cursor, do not replay events older than this |
| `heartbeatMs` | Optional: how often AGO confirms a quiet stream is alive, between 5,000 and 60,000 ms (30,000 by default) |

Each message of the stream is a JSON-RPC notification whose `params._meta["io.modelcontextprotocol/subscriptionId"]` is the `id` of your request:

| Message | When |
| - | - |
| `notifications/events/active` | First, with the starting `cursor`, `truncated` and the `heartbeatMs` AGO granted. Sent again with `truncated: true` if events were missed |
| `notifications/events/event` | For each matching event, with `eventId`, `name`, `timestamp`, `data` and its `cursor` |
| `notifications/events/heartbeat` | When nothing else was sent for `heartbeatMs`, with the current `cursor` |
| `notifications/events/terminated` | Your key lost access to the event: the stream ends with error `-32024` |

```text theme={null}
data: {"jsonrpc":"2.0","method":"notifications/events/event","params":{"eventId":"0b9c…","name":"ticket.created","timestamp":"2026-11-21T09:00:00+00:00","data":{"ticket_id":"8812","status_id":"open","previous_status_id":""},"cursor":"WyIyMDI2…","_meta":{"io.modelcontextprotocol/subscriptionId":"tickets-stream"}}}
```

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](https://ago.mintlify.site/features/workflows.md#choose-an-ago-event), not through MCP Events.

## Events

| Event | Scope | Filters | Data fields |
| - | - | - | - |
| `conversation.created` | `conversations:read` | `status_id` | `thread_id`, `status_id`, `previous_status_id` |
| `conversation.status_changed` | `conversations:read` | `status_id`, `previous_status_id` | `thread_id`, `status_id`, `previous_status_id` |
| `conversation.handoff_changed` | `conversations:read` | `handoff_state`, `previous_handoff_state` | `thread_id`, `ticket_id`, `handoff_state`, `previous_handoff_state` |
| `conversation.tagged` | `conversations:read` | `tag_id` | `thread_id`, `tag_id`, `tag_name` |
| `conversation.feedback_given` | `conversations:read` | `rating`, `source`, `agent_id` | `thread_id`, `message_id`, `agent_id`, `rating`, `source` |
| `conversation.evaluated` | `conversations:read` | `need_review` | `thread_id`, `cx_score`, `need_review` |
| `voice.call_ended` | `conversations:read` | `agent_id` | `thread_id`, `agent_id`, `duration_seconds`, `turn_count` |
| `ticket.created` | `tickets:read` | `status_id` | `ticket_id`, `status_id`, `previous_status_id` |
| `ticket.status_changed` | `tickets:read` | `status_id`, `previous_status_id` | `ticket_id`, `status_id`, `previous_status_id` |
| `ticket.priority_changed` | `tickets:read` | `priority`, `previous_priority` | `ticket_id`, `priority`, `previous_priority` |
| `ticket.assignee_changed` | `tickets:read` | `assignee_id` | `ticket_id`, `assignee_id`, `previous_assignee_id` |
| `ticket.team_changed` | `tickets:read` | `team_id` | `ticket_id`, `team_id`, `previous_team_id` |
| `ticket.message_added` | `tickets:read` | `author` | `ticket_id`, `message_id`, `author` |
| `customer.alert` | `crm:read` | `rule` | `alert_id`, `company_id`, `rule` |
| `form.submitted` | `conversations:read` | `form_name`, `status` | `submission_id`, `form_name`, `status`, `thread_id`, `user_email`, `values` |
| `knowledge.gap_detected` | `knowledge:read` | `agent_id`, `source`, `gap_type` | `request_id`, `thread_id`, `agent_id`, `source`, `gap_type`, `user_question`, `summary` |
| `mailbox.email_received` | `tickets:read` | `mailbox_id`, `category`, `needs_reply` | `mailbox_id`, `email_id`, `category`, `needs_reply`, `ticket_id` |
| `source.sync_failed` | `knowledge:read` | `source_type` | `source_id`, `source_type`, `source_name`, `error` |

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

| Code | Meaning |
| - | - |
| `-32023` | Unknown event name, an event that cannot be received, or no subscription matching `events/unsubscribe` |
| `-32024` | Your key lacks the scope the event requires |
| `-32025` | Your key already has 50 subscriptions, or 10 open streams (`data.limit` is `streams`) |
| `-32026` | A `delivery.mode` other than `webhook` in `events/subscribe` |
| `-32027` | Your endpoint did not answer the verification challenge; `data.reason` says why |
| `-32602` | Invalid `arguments`, `cursor`, `maxEvents`, `maxAgeMs`, `heartbeatMs`, `ttlMs`, `delivery.url` or `delivery.secret`; the message says which |

## Related

* [Webhooks](https://ago.mintlify.site/api/webhooks.md): create webhooks from the admin page or the REST API
* [MCP Server](https://ago.mintlify.site/api/mcp-tool-api.md)
* [OAuth Scopes](https://ago.mintlify.site/api/oauth-scopes.md)
* [Workflows](https://ago.mintlify.site/features/workflows.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.