@mastra/mcp 2.5.0-alpha.2 → 2.5.0-alpha.3

package/dist/docs/references/reference-tools-mcp-client.md

@@ -31,6 +31,8 @@ constructor({
 
 **clientInfo** (`{ name?: string; version?: string }`): Client name and version every server receives on connect and with each request, so servers can attribute traffic to your application. Defaults to the server key as name and '1.0.0' as version. Individual server configs can override either field with their own clientInfo. Doesn't change tool name prefixes, which always use the server key.
 
+**webhook** (`MCPClientWebhookOptions`): Experimental. Enables webhook delivery for MCP events. Servers POST occurrences to webhook.url, which must route to events.handleWebhook().
+
 ### `MastraMCPServerDefinition`
 
 Each server in the `servers` map is configured using the `MastraMCPServerDefinition` type. The transport type is detected based on the provided parameters:
@@ -761,6 +763,240 @@ Notes:
 - When `enableProgressTracking` is true, tool calls include a `progressToken` so you can correlate updates to a specific run. Servers only send progress for requests that carry a token.
 - If you pass a `runId` when executing a tool, it will be used as the `progressToken`.
 
+### `events` Property (experimental)
+
+The `events` property lists and subscribes to server events from servers that implement the [MCP Events extension (SEP-3415)](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/3415). Use it to react to things that happen on the server, such as a push to a repository, without polling a tool.
+
+For an end-to-end walkthrough, see the [MCP events guide](https://mastra.ai/docs/guides/mcp-events).
+
+> **Warning:** SEP-3415 is a draft. This API may change in any release.
+
+```typescript
+const events = await mcpClient.events.list('github')
+
+const subscription = await mcpClient.events.subscribe(
+  'github',
+  'repo.push',
+  { repo: 'mastra-ai/mastra' },
+  { cursor: await loadCursor() },
+)
+
+for await (const event of subscription) {
+  await handlePush(event.data)
+  // Safe to persist after each handled occurrence
+  await saveCursor(subscription.cursor)
+}
+```
+
+Servers that don't advertise the `io.modelcontextprotocol/events` extension receive no `events/*` requests. `list()` rejects with a `MastraError` whose id is `MCP_CLIENT_LIST_EVENTS_FAILED`, and `subscribe()` rejects with `MCP_CLIENT_SUBSCRIBE_EVENT_FAILED`. In both cases `error.cause.id` is `MCP_EVENTS_NOT_SUPPORTED`. Other `list()` and `subscribe()` failures use the same two ids, with the specific reason in `error.cause`.
+
+#### `events.list(serverName: string)`
+
+Returns every event type the server offers, following pagination. Each descriptor has a `name`, an optional `description`, the `delivery` modes the server supports, and optional `inputSchema` and `payloadSchema`.
+
+```typescript
+async list(serverName: string): Promise<MCPEventDescriptor[]>
+```
+
+The client doesn't receive notifications when the server's event list changes yet. Call `list()` again to pick up new event types.
+
+#### `events.subscribe(serverName, eventName, args?, options?)`
+
+Starts a subscription and resolves once the server confirms it. Errors such as an unknown event, invalid arguments, or a forbidden subscription reject the returned promise.
+
+```typescript
+async subscribe(
+  serverName: string,
+  eventName: string,
+  args?: Record<string, unknown>,
+  options?: MCPEventSubscribeOptions,
+): Promise<MCPEventSubscription>
+```
+
+The client picks the first mode the event offers in this order: `webhook` (only when the client has [`webhook` settings](#webhook-delivery)), `push` (a long-lived `events/stream` request), then `poll` (repeated `events/poll` requests). Pass `options.delivery` to force a mode.
+
+**delivery** (`'webhook' | 'push' | 'poll'`): Forces a delivery mode. When the event doesn't offer it, or for webhook without client webhook settings, subscribe() rejects with MCP\_CLIENT\_SUBSCRIBE\_EVENT\_FAILED and error.cause.id is MCP\_EVENTS\_NO\_COMPATIBLE\_DELIVERY\_MODE or MCP\_EVENTS\_WEBHOOK\_NOT\_CONFIGURED.
+
+**cursor** (`string | null`): Resumes from a cursor saved earlier. Omit or pass null to start from now.
+
+**maxAgeMs** (`number`): Asks the server not to replay occurrences older than this.
+
+**maxEvents** (`number`): Maximum occurrences per poll response. Poll mode only.
+
+**minPollIntervalMs** (`number`): Lower bound for the wait between polls, applied to the server-suggested nextPollMs. (Default: `1000`)
+
+**heartbeatTimeoutMs** (`number`): Push mode reopens the stream from the last cursor after this long without any message from the server. (Default: `60000`)
+
+**streamOpenTimeoutMs** (`number`): How long to wait for the server to confirm a push stream. Defaults to the server request timeout.
+
+**dedupWindow** (`number`): Number of recent event ids remembered to drop duplicate occurrences. (Default: `1000`)
+
+**maxBufferedEvents** (`number`): Most occurrences held while your loop isn't reading. When full, the oldest unread occurrence is dropped, the next one has truncated set, and onError receives MCP\_EVENTS\_BUFFER\_OVERFLOW. (Default: `1000`)
+
+**retry** (`{ initialDelayMs?: number; maxDelayMs?: number; factor?: number; maxAttempts?: number }`): Backoff with full jitter for transient failures. Defaults to 1000 ms initial delay, 30000 ms maximum, factor 2, unlimited retries.
+
+**signal** (`AbortSignal`): Aborting it cancels the subscription.
+
+The returned `MCPEventSubscription` is an async iterable of occurrences (`eventId`, `name`, `timestamp`, `data`) with these members:
+
+- `cursor`: The latest position that's safe to persist. It never moves past an occurrence your loop hasn't received yet. It's `null` when the event type doesn't support replay.
+- `truncated`: `true` when the server reported a gap right before the occurrence your loop received last, for example because the saved cursor was older than its retention window. Read it inside the loop: it's `true` for the first occurrence after the gap and `false` for the ones after it.
+- `mode`: The delivery mode in use, `'webhook'`, `'push'`, or `'poll'`.
+- `deliveryStatus`: Webhook mode only. The server's latest report on delivery to your webhook URL (`active`, `lastDeliveryAt`, `lastError`, `failedSince`), updated on each refresh.
+- `onError(handler)`: Receives recoverable errors, such as a dropped stream that the client is reopening. Returns a function that removes the handler.
+- `cancel()`: Stops the subscription and ends the iterator. Breaking out of a `for await` loop also cancels it.
+
+The iterator throws a `MastraError` directly (not wrapped) when the subscription can't continue: `MCP_EVENTS_SUBSCRIPTION_FAILED` for a non-retryable server error, `MCP_EVENTS_SUBSCRIPTION_TERMINATED` when the server ends a push or webhook subscription, or `MCP_EVENTS_RETRIES_EXHAUSTED` after `retry.maxAttempts` failed attempts in a row. The client reopens dropped streams and resumes polling from the last cursor after a reconnect, including after `reconnectServer()`. `disconnect()` ends all subscriptions.
+
+#### `events.handleWebhook(request: Request)`
+
+Handles one webhook delivery and returns the response to send back. Mount it on the route that `webhook.url` points at.
+
+```typescript
+async handleWebhook(request: Request): Promise<Response>
+```
+
+It verifies the Standard Webhooks signature on the raw body before parsing it, answers the server's verification handshake, and routes occurrences to their subscription by the `X-MCP-Subscription-Id` header. It responds with:
+
+- `200` after the occurrence is handed to its subscription, or with the echoed challenge for a verification request.
+- `401` when the signature is invalid or the timestamp is more than 5 minutes old.
+- `503` when the subscription id isn't known yet, so the server retries. This covers deliveries that arrive before the subscribe response.
+- `400` for a signed but malformed body, and `405` for methods other than `POST`.
+- `413` for a body over 1 MiB. The body is read only up to that limit, before any other check.
+- `404` when the client has no `webhook` settings.
+
+#### Webhook delivery
+
+With `webhook` settings, the client registers each subscription with `events/subscribe` and the server POSTs occurrences to your URL. The server must authenticate the client, and the URL must be publicly reachable over `https`.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { registerApiRoute } from '@mastra/core/server'
+import { MCPClient } from '@mastra/mcp'
+
+export const mcpClient = new MCPClient({
+  servers: {
+    github: {
+      url: new URL('https://mcp.example.com/mcp'),
+      requestInit: { headers: { Authorization: `Bearer ${process.env.GITHUB_MCP_TOKEN}` } },
+    },
+  },
+  webhook: { url: 'https://agent.example.com/mcp/webhook' },
+})
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      registerApiRoute('/mcp/webhook', {
+        method: 'POST',
+        // Deliveries are authenticated by their signature, not by Mastra auth
+        requiresAuth: false,
+        handler: c => mcpClient.events.handleWebhook(c.req.raw),
+      }),
+    ],
+  },
+})
+```
+
+**url** (`string`): Public https URL that routes to events.handleWebhook().
+
+**secret** (`string`): A whsec\_ signing secret used for every subscription. By default the client generates a fresh secret for each subscription, so one server can't sign deliveries for another server's subscriptions.
+
+**ttlMs** (`number | null`): Suggested subscription lifetime. null asks for no expiry, which the server may decline. Defaults to the server default.
+
+**refreshMarginMs** (`number`): How long before the server-granted refreshBefore time to refresh the subscription. Defaults to the smaller of 60 seconds and 20% of the grant.
+
+The client refreshes each subscription before it expires by repeating `events/subscribe` with the latest cursor. When the server reports failing delivery in `deliveryStatus`, for example because your endpoint timed out, `onError` receives `MCP_EVENTS_WEBHOOK_DELIVERY_FAILING` with `lastError` in its details. The next refresh resumes a suspended subscription. `cancel()` sends `events/unsubscribe`.
+
+Webhook state lives in this process: run the receiving route in the same process as the `MCPClient` that subscribed.
+
+Webhook delivery needs an authenticated HTTP connection to the server, because the server ties each webhook subscription to the caller. Over stdio, or over HTTP without authentication, the server rejects `events/subscribe`; it also rejects new subscriptions once its webhook subscription cap is reached (`-32025`). A subscription that didn't force a mode then falls back to `push` or `poll`, and the first `onError` handler receives `MCP_EVENTS_WEBHOOK_UNAVAILABLE` with the rejection `code` and the `fallback` mode in its details. Forcing `delivery: 'webhook'` rejects instead.
+
+Subscriptions on one server with the same event name and arguments share a single server-side webhook subscription. Each one gets every occurrence through its own iterator, and the client sends `events/unsubscribe` only when the last of them is cancelled.
+
+### Events in agents and workflows (experimental)
+
+`MCPEventsSignalProvider` delivers MCP server events to agent threads as notifications. Add it to an agent's `signals`, then subscribe threads to events. The agent needs a notifications storage domain, which `InMemoryStore` and the standard storage adapters provide.
+
+> **Warning:** SEP-3415 is a draft. This API may change in any release.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { MCPClient, MCPEventsSignalProvider } from '@mastra/mcp'
+
+const mcp = new MCPClient({
+  servers: { github: { url: new URL('https://example.com/mcp') } },
+})
+
+export const repoEvents = new MCPEventsSignalProvider({
+  client: mcp,
+  subscribeOptions: { maxAgeMs: 60 * 60 * 1000 },
+})
+
+export const repoAgent = new Agent({
+  id: 'repo-agent',
+  name: 'Repo Agent',
+  instructions: 'Triage repository activity.',
+  model: 'openai/gpt-5.6-sol',
+  signals: [repoEvents],
+})
+
+await repoEvents.subscribeThread(
+  { resourceId: 'user-1', threadId: 'thread-1' },
+  { server: 'github', event: 'repo.push', args: { repo: 'mastra-ai/mastra' } },
+)
+```
+
+Threads that subscribe to the same server, event and arguments share one MCP subscription. Argument key order doesn't matter. Each occurrence becomes a notification with `kind: 'mcp-event'` and `attributes: { server, event }`. The raw occurrence is in `payload`. The notification `summary`, which is the only part the model reads, labels the event as untrusted and wraps its data, together with the server-advertised event name, in an `<untrusted-mcp-event-data>` block that the content can't close. When the server reports a gap, `attributes.truncated` is `true` and the summary says that events may have been skipped.
+
+If the subscription ends, for example because the server terminates it, each subscribed thread receives a `high` priority notification with `kind: 'mcp-event-subscription-ended'` and the threads are unsubscribed.
+
+**client** (`Pick<MCPClient, 'events'>`): The client used to list and subscribe to events.
+
+**id** (`string`): Provider id, used as the notification source. (Default: `'mcp-events'`)
+
+**name** (`string`): Display name. (Default: `'MCP Events'`)
+
+**cursorStore** (`MCPEventCursorStore`): Stores the resume cursor for each subscription. Implement get(key), set(key, cursor) and delete(key) with durable storage so a subscription continues from its last cursor when a thread is subscribed again after a restart. Only cursors are stored, not which threads are subscribed. Only non-null cursors are stored. (Default: `InMemoryMCPEventCursorStore`)
+
+**subscribeOptions** (`Omit<MCPEventSubscribeOptions, 'cursor' | 'signal'>`): Options for every MCP subscription, for example maxAgeMs to bound the backlog replayed on resume.
+
+**priority** (`NotificationPriority`): Priority of event notifications. (Default: `'medium'`)
+
+**coalesce** (`boolean`): Sets coalesceKey: 'mcp-events:\<key>' on event notifications, whatever the provider id. Pending notifications from one subscription then merge, so a burst that arrives before the agent reads its inbox keeps only the latest occurrence. When off, every occurrence is its own notification. (Default: `false`)
+
+**tools** (`boolean | { servers: string[] }`): Gives the agent the mcp\_events\_list, mcp\_events\_subscribe and mcp\_events\_unsubscribe tools, which act on the current thread and require memory. Event descriptions and error messages from the server reach the model inside the same untrusted-data block as event data. Subscriptions made through the tools are lost on restart. Pass servers to limit them to those servers. (Default: `false`)
+
+**onError** (`(error: unknown, info: { server: string; event: string; key: string }) => void`): Receives delivery, cursor store and subscription errors.
+
+The provider has these methods:
+
+- `subscribeThread(thread, { server, event, args? })`: Subscribes a thread and resolves once the MCP subscription is confirmed. It resumes from the stored cursor. If the server rejects the subscription, the thread isn't subscribed and the promise rejects. Thread subscriptions are kept in memory only: after a restart, call `subscribeThread()` again for each thread that should keep receiving events.
+- `unsubscribeThread(thread, { server, event, args? })`: Resolves to `true` when the thread was subscribed. When the last thread leaves, the MCP subscription is cancelled and its stored cursor is deleted.
+- `stop()`: Cancels every MCP subscription and keeps the stored cursors, so a new provider with the same `cursorStore` resumes where this one stopped.
+- `MCPEventsSignalProvider.key({ server, event, args? })`: Returns the subscription key used by the cursor store.
+
+Delivery is at least once. The provider stores the cursor after it notifies the threads, so an occurrence notified right before a crash is replayed after the restart. The notification's `dedupeKey` includes the event id: if the first notification is still pending, the replay merges into it. If it was already delivered, the thread is notified again.
+
+To start a workflow run for each occurrence, iterate a subscription directly:
+
+```typescript
+const subscription = await mcp.events.subscribe(
+  'github',
+  'repo.push',
+  { repo: 'mastra-ai/mastra' },
+  { cursor: await loadCursor() },
+)
+
+process.once('SIGTERM', () => void subscription.cancel())
+
+for await (const event of subscription) {
+  const run = await triagePushWorkflow.createRun()
+  await run.start({ inputData: { eventId: event.eventId, push: event.data } })
+  if (subscription.cursor) await saveCursor(subscription.cursor)
+}
+```
+
 ## Answering input requests
 
 A server tool, resource or prompt that needs something from the user ends its call with an `input_required` result instead of a value. The result carries one or more embedded requests, each with a server-chosen `key` and either a form (`requestedSchema`) or a URL the user must visit. Configure `inputRequests` on the server definition to answer them: the client calls the handler once per embedded request, retries the original call with the answers, and resolves the tool call with the final result. Without a handler an `input_required` result surfaces as an error.

package/dist/docs/references/reference-tools-mcp-server.md

@@ -1414,6 +1414,176 @@ const server = new MCPServer({
 
 Link a tool to its app resource by setting `mcp._meta.ui.resourceUri` in `createTool()` to the matching `ui://` URI. The server normalizes this metadata for older hosts when listing tools, and returns the same link on successful tool call results. Visit [MCP Apps](https://mastra.ai/docs/connections/mcp) for the full app bridge API and usage patterns.
 
+## Events (experimental)
+
+> **Warning:** Events implement [SEP-3415](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/3415), a draft MCP extension. The wire format and this API may change in any release.
+
+For an end-to-end walkthrough, see the [MCP events guide](https://mastra.ai/docs/guides/mcp-events).
+
+The `events` option lets clients subscribe to things that happen on your server, such as a ticket being created or a build finishing. The server advertises the `io.modelcontextprotocol/events` extension and answers `events/list`, `events/poll` and `events/stream` over both stdio and Streamable HTTP. With [`eventsOptions.webhook`](#webhook-delivery) set, it also answers `events/subscribe` and `events/unsubscribe` and POSTs occurrences to client webhook URLs.
+
+Declare each event type with `defineEvent()` and publish occurrences with `server.events.emit()`:
+
+```typescript
+import { MCPServer, defineEvent } from '@mastra/mcp'
+import { z } from 'zod'
+
+const server = new MCPServer({
+  id: 'tickets',
+  name: 'Tickets',
+  version: '1.0.0',
+  tools: {},
+  events: {
+    'ticket.created': defineEvent({
+      description: 'A ticket was created',
+      inputSchema: z.object({ project: z.string().optional() }),
+      payloadSchema: z.object({ id: z.string(), project: z.string() }),
+      match: (args, data) => !args.project || data.project === args.project,
+    }),
+  },
+})
+
+await server.events.emit('ticket.created', { id: 't-1', project: 'web' })
+```
+
+A client that subscribed with `{ project: 'web' }` receives this occurrence. A client that subscribed with `{ project: 'api' }` doesn't.
+
+`match` filters on the arguments the client chooses, so it doesn't control who can subscribe. To restrict callers, add `authorize`. It receives the validated arguments and the caller's `requestContext`, which includes `user` when you set `mapAuthInfoToUser`:
+
+```typescript
+const ticketCreated = defineEvent({
+  inputSchema: z.object({ project: z.string() }),
+  payloadSchema: z.object({ id: z.string(), project: z.string() }),
+  match: (args, data) => data.project === args.project,
+  authorize: ({ arguments: args, requestContext }) => {
+    const user = requestContext.get('user') as { projects: string[] } | undefined
+    return user?.projects.includes(args.project) ?? false
+  },
+})
+```
+
+`authorize` runs on every `events/poll`, every `events/stream` open, and every webhook `events/subscribe`, including refreshes. An open stream isn't checked again until it reconnects, and a webhook subscription until its next refresh. A caller who loses access keeps receiving occurrences until then. FGA isn't applied to events; use `authorize` to restrict them.
+
+### `defineEvent()` options
+
+**description** (`string`): Description returned by events/list.
+
+**inputSchema** (`StandardSchemaWithJSON`): Schema for the subscription arguments. Advertised as JSON Schema. Arguments that fail validation are rejected with error -32602, and match and poll receive the parsed value.
+
+**payloadSchema** (`StandardSchemaWithJSON`): Schema for the event data. Advertised as JSON Schema and enforced by server.events.emit().
+
+**match** (`(args, data) => boolean`): Decides whether an emitted event reaches a subscription with these arguments. Applies to push streams and to polls served from the buffer. Defaults to delivering every event.
+
+**authorize** (`(context) => boolean | Promise<boolean>`): Decides whether the caller may receive this type with these arguments. Receives arguments, requestContext and delivery ('poll', 'push' or 'webhook'). Runs on every events/poll, before a poll source is called, on every events/stream open, and on every webhook events/subscribe, including refreshes. Returning false rejects the request with -32024. A refresh that is denied also removes the webhook subscription. If it throws, the client gets a generic -32603 error and the details are logged on the server. Defaults to allowing every caller.
+
+**poll** (`(context) => Promise<MCPServerEventPollResult>`): Pull source for events/poll. Receives arguments, cursor (null means start from now), maxEvents, maxAgeMs, requestContext and signal. Returns { events, cursor, hasMore?, nextPollMs?, truncated? }. Each event needs data and a stable eventId (clients dedupe by it, so return the same id whenever the same occurrence is polled); a missing timestamp defaults to now. If poll or match throws, the client gets a generic -32603 error and the details are logged on the server.
+
+**delivery** (`Array<'poll' | 'push' | 'webhook'>`): Restricts the advertised delivery modes to this list. It only narrows the modes from the table below, and a definition left with no mode throws when the server is constructed.
+
+**bufferSize** (`number`): Number of emitted events kept in memory for replay and buffered polls. (Default: `1000`)
+
+**pollIntervalMs** (`number`): nextPollMs suggested to clients that poll the buffer.
+
+### Delivery modes
+
+How a type is served depends on where its events come from:
+
+| Definition | Advertised `delivery`                                                    | Source                                                   |
+| ---------- | ------------------------------------------------------------------------ | -------------------------------------------------------- |
+| No `poll`  | `['push', 'poll']`, plus `'webhook'` when `eventsOptions.webhook` is set | `server.events.emit()`. Polls read the in-memory buffer. |
+| `poll`     | `['poll']`                                                               | Your `poll` function, called for each `events/poll`.     |
+
+A type with a `poll` source can't also be pushed: `delivery` can't add `'push'` to it, and `server.events.emit()` throws for it. The advertised modes never change after the server starts, because clients only learn them from `events/list`. To push events, define a type without `poll` and emit to it.
+
+A request for a mode the type doesn't advertise fails with `-32026`. An unknown event name fails with `-32023`.
+
+### Push streams
+
+Each `events/stream` request is one subscription. The server sends `notifications/events/active` first, then one `notifications/events/event` per matching occurrence. Every notification carries the request id as `_meta["io.modelcontextprotocol/subscriptionId"]`. When the request includes a `cursor`, buffered events after it are replayed before live ones. If that cursor is older than the buffer, `active` reports `truncated: true`.
+
+When no other message has been sent for `heartbeatIntervalMs`, the stream sends `notifications/events/heartbeat` with the current cursor. Cancelling the request, or calling `server.close()`, ends the stream and releases its listener and timer.
+
+### `eventsOptions`
+
+**heartbeatIntervalMs** (`number`): Longest gap between messages on a push stream. (Default: `30000`)
+
+**listPageSize** (`number`): Number of event types per events/list page. (Default: `100`)
+
+**maxStreams** (`number`): Most push streams open at once across all clients. Further events/stream requests are rejected with -32025 until one closes. A Mastra client retries the rejection when reconnecting an established subscription; a new subscribe() call rejects with it. (Default: `1024`)
+
+**webhook** (`MCPServerWebhookOptions`): Enables webhook delivery for event types without a poll source. Without it, the server doesn't advertise webhook or answer events/subscribe.
+
+### Webhook delivery
+
+With `eventsOptions.webhook` set, a client can register a callback URL with `events/subscribe`, and the server POSTs each matching occurrence to it, signed with the client's secret using [Standard Webhooks](https://www.standardwebhooks.com/) HMAC-SHA256.
+
+```typescript
+const server = new MCPServer({
+  id: 'tickets',
+  name: 'Tickets',
+  version: '1.0.0',
+  tools: {},
+  events: {
+    'ticket.created': defineEvent({ payloadSchema: z.object({ id: z.string() }) }),
+  },
+  eventsOptions: {
+    webhook: { ttl: { defaultMs: 30 * 60_000 } },
+  },
+})
+```
+
+The server enforces these rules:
+
+- **Authentication:** Webhook subscriptions need an authenticated caller. Without `authInfo` on the request, `events/subscribe` fails with `-32024`. A subscription is identified by the caller, the URL, the event name, and the arguments, so repeating `events/subscribe` refreshes the same subscription and returns the same `id`.
+- **Authorization:** `authorize` runs on each subscribe and each refresh. When it denies a refresh, the subscription is removed and no further occurrences are POSTed. A Mastra client can't tell this `-32024` from the one for an unauthenticated caller, so in its default delivery mode it reports `MCP_EVENTS_WEBHOOK_UNAVAILABLE`, tries push, and then rejects with the same `-32024`.
+- **Callback URLs:** The URL must use `https`. Every address it resolves to must be publicly routable: loopback, private, link-local, and other special-purpose ranges are rejected with `-32602` and `data.reason`. The check runs again before every delivery, and the request connects to the address that passed, to prevent DNS rebinding. Redirects are never followed.
+- **Verification:** Before the first delivery to a URL, the server POSTs a signed verification challenge, and the endpoint must echo it. A failed or unreachable endpoint fails `events/subscribe` with `-32027` and a `data.reason` such as `challenge_failed` or `timeout`. The result is cached per caller and URL. URLs accepted by `allowedUrls` skip this step.
+- **Lifetime:** Each subscription expires at the returned `refreshBefore` time unless the client refreshes it. A requested `ttlMs` is clamped to the `ttl` bounds.
+- **Retries:** Each occurrence is retried with exponential backoff until it's acknowledged with a `2xx`, `retry.maxAttempts` is reached, or `retry.maxWindowMs` has passed. A `410` or `413` response stops retries for that occurrence. The `cursor` in each body only advances past occurrences that are acknowledged or given up on.
+- **Suspension:** When most deliveries to a subscription fail over `suspend.windowMs`, the server pauses it and reports `active: false` in `deliveryStatus` on the next refresh. The refresh resumes delivery.
+- **Errors:** Clients only see a failure category such as `timeout` or `http_5xx`, never the endpoint's response body or headers.
+
+**ttl** (`{ defaultMs?: number; minMs?: number; maxMs?: number }`): Subscription lifetime granted when the client omits ttlMs, and the bounds a requested ttlMs is clamped to. Defaults to 30 minutes, 60 seconds, and 24 hours.
+
+**allowNoExpiry** (`boolean`): Grants ttlMs: null requests a subscription that never expires. Otherwise they get ttl.maxMs. Only enable it with a durable store, because clients with no-expiry subscriptions don't need to refresh after a server restart. (Default: `false`)
+
+**store** (`WebhookSubscriptionStore`): Stores subscription records (identity, secret, expiry) with async get, set, delete, and list methods. The default keeps them in memory, so subscriptions are lost on restart until clients refresh. (Default: `InMemoryWebhookSubscriptionStore`)
+
+**url** (`{ allowPrivate?: boolean; allowInsecure?: boolean; lookup?: WebhookLookup }`): Callback URL policy. allowPrivate accepts non-public addresses and allowInsecure accepts http. Use them for local development only. lookup replaces DNS resolution.
+
+**allowedUrls** (`(url: URL) => boolean`): Returns true for URLs you trust, which then skip the verification challenge.
+
+**verificationTtlMs** (`number`): How long a successful verification is remembered for a caller and URL. (Default: `86400000`)
+
+**timeoutMs** (`number`): Timeout for each delivery attempt. (Default: `5000`)
+
+**retry** (`{ maxAttempts?: number; initialDelayMs?: number; maxDelayMs?: number; maxWindowMs?: number }`): Retry policy for each occurrence. Defaults to 5 attempts, a 1 second initial delay, a 5 minute maximum delay, and a 15 minute window. Time spent suspended doesn't count against the window.
+
+**suspend** (`{ windowMs?: number; minAttempts?: number; failureRate?: number }`): Suspends a subscription when at least failureRate of at least minAttempts attempts fail within windowMs. Defaults to 0.95, 100, and 60 minutes.
+
+**maxPending** (`number`): Undelivered occurrences kept per subscription. On overflow the oldest are dropped and the client receives a gap body, so it reports truncated: true. (Default: `1000`)
+
+**maxSubscriptions** (`number`): Most webhook subscriptions this process keeps across all callers. New subscriptions past the limit are rejected with -32025, and a Mastra client falls back to push or poll unless it forced webhook delivery. Refreshing an existing subscription still works. (Default: `1000`)
+
+**maxSubscriptionsPerPrincipal** (`number`): Most webhook subscriptions one authenticated caller can hold. (Default: `100`)
+
+**secretGraceMs** (`number`): After a client rotates its secret, deliveries are signed with both secrets for this long. (Default: `300000`)
+
+**transport** (`WebhookTransport`): Replaces the HTTP client that sends deliveries, for example in tests.
+
+### `server.events.emit(name, data, options?)`
+
+Records an occurrence, delivers it to matching push streams and webhook subscriptions, and returns it with its `eventId`, `timestamp` and `cursor`. `options.eventId` and `options.timestamp` override the defaults (a random UUID and the current time). It throws when `name` isn't configured, when `data` fails `payloadSchema`, or when the type has a `poll` source.
+
+`server.events.list()` returns the descriptors `events/list` serves.
+
+### Limits
+
+- Emitted events stay in the process that emitted them. Push streams, webhook subscriptions, and buffered polls only see events emitted by the same `MCPServer` instance, so a serverless or multi-instance deployment needs a `poll` source backed by shared storage.
+- The buffer is in memory. A restarted server treats earlier cursors as a gap and reports `truncated: true`.
+- Webhook delivery state (pending retries, suspension, verification results) is in memory and rebuilt when clients refresh.
+- Changes to the list of event types aren't announced yet. The server doesn't advertise `listChanged` or send `notifications/events/list_changed`, because the MCP TypeScript SDK 2.2.0 doesn't carry the `eventsListChanged` filter on `subscriptions/listen`. Clients should re-run `events/list` to see changed event types.
+
 ## Related information
 
 - For connecting to MCP servers in Mastra, see the [MCPClient documentation](https://mastra.ai/reference/tools/mcp-client).