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

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