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

package/dist/server/events/types.d.ts

@@ -0,0 +1,203 @@
+import type { RequestContext } from '@mastra/core/request-context';
+import type { PublicSchema } from '@mastra/core/schema';
+import type { EventDeliveryMode, WebhookUrlPolicyOptions } from '../../shared/events/index.js';
+import type { WebhookSubscriptionStore } from './webhook-store.js';
+import type { WebhookTransport } from './webhook-transport.js';
+/** Subscription arguments of an event type. @experimental SEP-3415 is a draft; this API may change. */
+export type MCPServerEventArgs = Record<string, unknown>;
+/** Payload (`data`) of an event occurrence. @experimental SEP-3415 is a draft; this API may change. */
+export type MCPServerEventData = Record<string, unknown>;
+/**
+ * What a `poll` source receives for one `events/poll` request.
+ *
+ * @experimental SEP-3415 is a draft; this API may change.
+ */
+export interface MCPServerEventPollContext<TArgs extends MCPServerEventArgs = MCPServerEventArgs> {
+    /** Subscription arguments, validated against `inputSchema` when one is set. */
+    arguments: TArgs;
+    /** Cursor from the previous poll, or `null` to start from now (no replay). */
+    cursor: string | null;
+    /** Upper bound on the number of events to return. */
+    maxEvents: number;
+    /** The client asks not to replay events older than this many milliseconds. */
+    maxAgeMs?: number;
+    requestContext: RequestContext;
+    /** Aborted when the client cancels the request. */
+    signal: AbortSignal;
+}
+/**
+ * What `authorize` receives when a client polls or subscribes to an event type.
+ *
+ * @experimental SEP-3415 is a draft; this API may change.
+ */
+export interface MCPServerEventAuthorizeContext<TArgs extends MCPServerEventArgs = MCPServerEventArgs> {
+    /** Subscription arguments, validated against `inputSchema` when one is set. */
+    arguments: TArgs;
+    /** The caller's request context, including `user` when the server maps one from the request's auth info. */
+    requestContext: RequestContext;
+    /** How the caller asked to receive events. */
+    delivery: EventDeliveryMode;
+}
+/**
+ * An event returned by a `poll` source. The server fills in `eventId` (random UUID) and
+ * `timestamp` (now) when they are absent.
+ *
+ * @experimental SEP-3415 is a draft; this API may change.
+ */
+export interface MCPServerPolledEvent<TData extends MCPServerEventData = MCPServerEventData> {
+    data: TData;
+    /**
+     * Stable id of the occurrence. Clients dedupe by it across polls and reconnections, so return
+     * the same id every time the same occurrence is polled (for example the upstream record id).
+     */
+    eventId: string;
+    /** When the event occurred. Defaults to the time of the poll. */
+    timestamp?: string | Date;
+}
+/** @experimental SEP-3415 is a draft; this API may change. */
+export interface MCPServerEventPollResult<TData extends MCPServerEventData = MCPServerEventData> {
+    events: MCPServerPolledEvent<TData>[];
+    /** Position after the returned events, or `null` for a non-replayable source. */
+    cursor: string | null;
+    hasMore?: boolean;
+    nextPollMs?: number;
+    truncated?: boolean;
+}
+/**
+ * Definition of one event type served by `MCPServer`.
+ *
+ * Without `poll`, the type is fed by `server.events.emit()` and is served over push
+ * (`events/stream`) and poll (`events/poll`, from a per-type ring buffer). With `poll`, the
+ * type is served over poll only, by calling `poll` for each request; it can't also be pushed,
+ * and `server.events.emit()` rejects it.
+ *
+ * @experimental SEP-3415 is a draft; this API may change.
+ */
+export interface MCPServerEventDefinition<TArgs extends MCPServerEventArgs = MCPServerEventArgs, TData extends MCPServerEventData = MCPServerEventData> {
+    description?: string;
+    /** Schema for subscription `arguments`. Advertised as JSON Schema in `events/list`. */
+    inputSchema?: PublicSchema<TArgs>;
+    /** Schema for event `data`. Advertised in `events/list` and enforced by `emit()`. */
+    payloadSchema?: PublicSchema<TData>;
+    /**
+     * Decides whether an emitted event reaches a subscription with these arguments. Defaults to all.
+     * The client chooses the arguments, so `match` doesn't restrict who can subscribe; use
+     * `authorize` for that.
+     */
+    match?(args: TArgs, data: TData): boolean;
+    /**
+     * Decides whether the caller may receive this event type with these arguments. Runs on every
+     * `events/poll`, every `events/stream` open and every webhook `events/subscribe`, including
+     * refreshes; returning `false` rejects the request with -32024 and, for a webhook, removes the
+     * existing subscription. An open stream isn't checked again until it reconnects, and a webhook
+     * until its next refresh. Defaults to allowing everyone.
+     */
+    authorize?(context: MCPServerEventAuthorizeContext<TArgs>): boolean | Promise<boolean>;
+    /** Pull source serving `events/poll`. */
+    poll?(context: MCPServerEventPollContext<TArgs>): Promise<MCPServerEventPollResult<TData>>;
+    /**
+     * Restricts the advertised delivery modes to this list. It only narrows: a mode the
+     * definition can't serve (for example `'push'` on a type with `poll`) is dropped, and a
+     * definition left with none fails at construction.
+     */
+    delivery?: EventDeliveryMode[];
+    /** Number of emitted events retained for replay and ring-buffer polls. Defaults to 1000. */
+    bufferSize?: number;
+    /** `nextPollMs` suggested to clients polling the ring buffer. */
+    pollIntervalMs?: number;
+}
+/**
+ * Server-wide events settings.
+ *
+ * @experimental SEP-3415 is a draft; this API may change.
+ */
+export interface MCPServerEventsOptions {
+    /** Longest gap between messages on an `events/stream`. Defaults to 30 000 ms. */
+    heartbeatIntervalMs?: number;
+    /** Descriptors per `events/list` page. Defaults to 100. */
+    listPageSize?: number;
+    /**
+     * Most `events/stream` requests this server keeps open at once, across all clients. Further
+     * requests are rejected with -32025 until a stream closes. Defaults to 1024.
+     */
+    maxStreams?: number;
+    /**
+     * Enables webhook delivery (`events/subscribe`, `events/unsubscribe`) for event types fed by
+     * `server.events.emit()`. Types with a `poll` source stay poll-only. Webhook subscriptions need an
+     * authenticated caller, so serve the server over HTTP with authentication.
+     */
+    webhook?: MCPServerWebhookOptions;
+}
+/**
+ * Webhook delivery settings.
+ *
+ * @experimental SEP-3415 is a draft; this API may change.
+ */
+export interface MCPServerWebhookOptions {
+    /** Subscription lifetimes granted for the client's `ttlMs` suggestion. */
+    ttl?: {
+        /** Granted when the client suggests none. Defaults to 30 minutes. */
+        defaultMs?: number;
+        /** Shorter suggestions are raised to this. Defaults to 60 seconds. */
+        minMs?: number;
+        /** Longer suggestions are lowered to this. Defaults to 24 hours. */
+        maxMs?: number;
+    };
+    /**
+     * Grant `ttlMs: null` (no expiry) when a client asks for it. Defaults to `false`, which grants
+     * `ttl.maxMs` instead. No-expiry subscriptions must survive restarts, so enable this only with a
+     * durable `store`.
+     */
+    allowNoExpiry?: boolean;
+    /** Where subscriptions are kept. Defaults to an in-memory store. */
+    store?: WebhookSubscriptionStore;
+    /** Callback URL policy. By default only `https` URLs that resolve to public addresses are accepted. */
+    url?: WebhookUrlPolicyOptions;
+    /** Callback URLs that count as verified without a challenge handshake. */
+    allowedUrls?: (url: URL) => boolean;
+    /** How long a successful handshake verifies a `(principal, url)` pair. Defaults to 24 hours. */
+    verificationTtlMs?: number;
+    /** Time allowed for one POST. Defaults to 5 seconds. */
+    timeoutMs?: number;
+    /** Retries of one delivery after a failure. Exponential backoff with jitter. */
+    retry?: {
+        /** Attempts per event, including the first. Defaults to 5. */
+        maxAttempts?: number;
+        /** Defaults to 1 second. */
+        initialDelayMs?: number;
+        /** Defaults to 5 minutes. */
+        maxDelayMs?: number;
+        /** Time after the first attempt after which an event is abandoned. Suspended time does not count. Defaults to 15 minutes. */
+        maxWindowMs?: number;
+    };
+    /** When delivery to an endpoint is suspended (`deliveryStatus.active: false`) until the client refreshes. */
+    suspend?: {
+        /** Rolling window the failure rate is measured over. Defaults to 60 minutes. */
+        windowMs?: number;
+        /** Attempts in the window needed before suspending. Defaults to 100. */
+        minAttempts?: number;
+        /** Failure ratio that suspends. Defaults to 0.95. */
+        failureRate?: number;
+    };
+    /** Undelivered events held per subscription before the oldest are dropped and a `gap` is sent. Defaults to 1000. */
+    maxPending?: number;
+    /**
+     * Most webhook subscriptions this process keeps, across all callers. A new subscription past
+     * the limit is rejected with -32025; refreshing an existing one is not. Defaults to 1000.
+     */
+    maxSubscriptions?: number;
+    /** Most webhook subscriptions one authenticated caller can hold. Defaults to 100. */
+    maxSubscriptionsPerPrincipal?: number;
+    /** How long deliveries are signed with both the old and the new secret after a rotation. Defaults to 5 minutes. */
+    secretGraceMs?: number;
+    /** Sends one POST. Defaults to `node:http`/`node:https`, connecting to the validated address. */
+    transport?: WebhookTransport;
+}
+/** @experimental SEP-3415 is a draft; this API may change. */
+export interface MCPServerEmitOptions {
+    /** Unique id clients deduplicate by. Defaults to a random UUID. */
+    eventId?: string;
+    /** When the event happened. Defaults to now. */
+    timestamp?: string | Date;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/server/events/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/server/events/types.ts"],"names":[],"mappings":"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"}

package/dist/server/events/webhook-dispatcher.d.ts

@@ -0,0 +1,98 @@
+import type { IMastraLogger } from '@mastra/core/logger';
+import type { SubscribeEventsRequestParams, SubscribeEventsResult } from '../../shared/events/index.js';
+import type { RegisteredEvent, ServerEventRegistry } from './registry.js';
+import type { MCPServerWebhookOptions } from './types.js';
+export interface WebhookDispatcherConfig {
+    registry: ServerEventRegistry;
+    options: MCPServerWebhookOptions;
+    getLogger: () => IMastraLogger;
+    /** Source of retry jitter; tests pin it. */
+    random?: () => number;
+}
+/**
+ * Serves webhook delivery for one `MCPServer`: `events/subscribe` upserts, endpoint verification,
+ * fan-out of emitted events, signed POSTs with retries, the safe-to-persist watermark, suspension
+ * and control envelopes.
+ *
+ * Subscriptions live in the configured {@link WebhookSubscriptionStore}; delivery state is in
+ * memory and only reaches this process's subscriptions.
+ */
+export declare class WebhookDispatcher {
+    private readonly config;
+    private readonly settings;
+    private readonly store;
+    private readonly transport;
+    private readonly states;
+    /** New subscriptions that passed the capacity check and are still being set up, by id → principal. */
+    private readonly reserved;
+    private readonly verified;
+    private readonly fanOutChains;
+    private readonly unsubscribers;
+    private readonly random;
+    private closed;
+    constructor(config: WebhookDispatcherConfig);
+    /** Subscription id for a key: a truncated SHA-256 over the canonical key. A routing handle, not a capability. */
+    static subscriptionId(key: {
+        principal: string;
+        url: string;
+        name: string;
+        arguments: Record<string, unknown>;
+    }): string;
+    /**
+     * Creates or refreshes the subscription keyed by `(principal, url, name, args)`.
+     * @throws ProtocolError `InvalidParams` for a disallowed callback URL, `CallbackEndpointError` when
+     * the endpoint fails verification.
+     */
+    subscribe(event: RegisteredEvent, args: Record<string, unknown>, params: SubscribeEventsRequestParams, principal: string): Promise<SubscribeEventsResult>;
+    private establish;
+    private assertCapacity;
+    /** Records a verified `(principal, url)` pair, dropping expired pairs and the oldest past a cap. */
+    private rememberVerified;
+    private persist;
+    /** Removes the subscription with this key, if any. Answers the same either way. */
+    unsubscribe(key: {
+        principal: string;
+        url: string;
+        name: string;
+        arguments: Record<string, unknown>;
+    }): Promise<void>;
+    /** Stops every timer and retry. */
+    close(): void;
+    private grantTtl;
+    private resolveUrl;
+    private isVerified;
+    /** The challenge handshake: the endpoint must echo a fresh nonce from a `2xx` response. */
+    private verify;
+    private createState;
+    private onEmit;
+    private fanOut;
+    private matches;
+    /** Advances past an event this subscription does not receive. */
+    private skip;
+    private enqueue;
+    /** Drops every undelivered event and tells the endpoint where delivery resumes with a `gap`. */
+    private overflow;
+    private attempt;
+    private scheduleRetry;
+    private settle;
+    private recordOutcome;
+    /** Suspends delivery once the failure rate over the window crosses the threshold. */
+    private maybeSuspend;
+    /** A refresh is the client's liveness signal: reactivate a suspended subscription and retry what is pending. */
+    private resume;
+    private terminate;
+    /** Sends a control envelope (`gap`, `terminated`), retrying with backoff up to `maxAttempts` attempts. */
+    private sendControl;
+    /** One signed POST to a subscription's endpoint, re-validating the URL so DNS cannot rebind it. */
+    private deliver;
+    private post;
+    private statusOf;
+    private isExpired;
+    private expiryTimers;
+    private scheduleExpiry;
+    private expire;
+    private dropState;
+    private setTimer;
+    private clearTimer;
+}
+//# sourceMappingURL=webhook-dispatcher.d.ts.map

package/dist/server/events/webhook-dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-dispatcher.d.ts","sourceRoot":"","sources":["../../../src/server/events/webhook-dispatcher.ts"],"names":[],"mappings":"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"}

package/dist/server/events/webhook-store.d.ts

@@ -0,0 +1,60 @@
+/**
+ * One webhook subscription as held by the server: the immutable subscription key, the derived
+ * `id`, the signing secret and the granted lifetime.
+ *
+ * @experimental SEP-3415 is a draft; this API may change.
+ */
+export interface WebhookSubscriptionRecord {
+    /** Derived from the key; carried in `X-MCP-Subscription-Id`. */
+    id: string;
+    /** Canonical identifier of the authenticated subject that subscribed. */
+    principal: string;
+    /** Callback URL (`delivery.url`). */
+    url: string;
+    /** Event name. */
+    name: string;
+    /** Validated subscription arguments. */
+    arguments: Record<string, unknown>;
+    /** Current `whsec_` signing secret. */
+    secret: string;
+    /** The secret replaced by the latest rotation, still used to dual-sign until `until` (epoch ms). */
+    previousSecret?: {
+        secret: string;
+        until: number;
+    };
+    /** Expiry in epoch ms, or `null` for a no-expiry grant. */
+    expiresAt: number | null;
+    /** Creation time in epoch ms. */
+    createdAt: number;
+}
+/**
+ * Where `MCPServer` keeps webhook subscriptions. The default keeps them in memory, which suits short
+ * TTL grants: after a restart clients resubscribe on their next refresh. A server that grants
+ * no-expiry subscriptions (`allowNoExpiry`) must persist them, so it needs a durable store.
+ *
+ * In-flight delivery state (retry queue, watermark, delivery status) is not stored here; it stays
+ * in memory and is rebuilt by the client's next refresh.
+ *
+ * @experimental SEP-3415 is a draft; this API may change.
+ */
+export interface WebhookSubscriptionStore {
+    get(id: string): Promise<WebhookSubscriptionRecord | undefined>;
+    /** Inserts or replaces the record with this `id`. */
+    set(record: WebhookSubscriptionRecord): Promise<void>;
+    delete(id: string): Promise<void>;
+    /** Every record subscribed to event `name`, including expired ones. */
+    list(name: string): Promise<WebhookSubscriptionRecord[]>;
+}
+/**
+ * Default {@link WebhookSubscriptionStore}: a process-local map.
+ *
+ * @experimental SEP-3415 is a draft; this API may change.
+ */
+export declare class InMemoryWebhookSubscriptionStore implements WebhookSubscriptionStore {
+    private readonly records;
+    get(id: string): Promise<WebhookSubscriptionRecord | undefined>;
+    set(record: WebhookSubscriptionRecord): Promise<void>;
+    delete(id: string): Promise<void>;
+    list(name: string): Promise<WebhookSubscriptionRecord[]>;
+}
+//# sourceMappingURL=webhook-store.d.ts.map

package/dist/server/events/webhook-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-store.d.ts","sourceRoot":"","sources":["../../../src/server/events/webhook-store.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,gEAAgE;IAChE,EAAE,EAAE,MAAM,CAAC;IACX,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,oGAAoG;IACpG,cAAc,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,2DAA2D;IAC3D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,wBAAwB;IACvC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,GAAG,SAAS,CAAC,CAAC;IAChE,qDAAqD;IACrD,GAAG,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,uEAAuE;IACvE,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,EAAE,CAAC,CAAC;CAC1D;AAED;;;;GAIG;AACH,qBAAa,gCAAiC,YAAW,wBAAwB;IAC/E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgD;IAElE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,GAAG,SAAS,CAAC,CAEpE;IAEK,GAAG,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1D;IAEK,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtC;IAEK,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,EAAE,CAAC,CAE7D;CACF"}

package/dist/server/events/webhook-transport.d.ts

@@ -0,0 +1,44 @@
+import type { WebhookFailureReason } from '../../shared/events/index.js';
+/**
+ * One POST to a callback endpoint.
+ *
+ * @experimental SEP-3415 is a draft; this API may change.
+ */
+export interface WebhookTransportRequest {
+    url: URL;
+    /** Validated IP to connect to. The hostname in `url` is used only for TLS SNI and the `Host` header. */
+    address: string;
+    family: 4 | 6;
+    headers: Record<string, string>;
+    body: string;
+    timeoutMs: number;
+}
+/**
+ * Outcome of one POST: the response status and (truncated) body, or the failure category when
+ * there was no HTTP response.
+ *
+ * @experimental SEP-3415 is a draft; this API may change.
+ */
+export type WebhookTransportResult = {
+    status: number;
+    body: string;
+} | {
+    error: WebhookFailureReason;
+};
+/**
+ * Sends one webhook POST. Must not follow redirects.
+ *
+ * @experimental SEP-3415 is a draft; this API may change.
+ */
+export type WebhookTransport = (request: WebhookTransportRequest) => Promise<WebhookTransportResult>;
+/** Maps a non-2xx status to its failure category. */
+export declare function statusFailure(status: number): WebhookFailureReason;
+/**
+ * Default {@link WebhookTransport}: `node:http`/`node:https` connecting to the pinned address, so a
+ * DNS answer that changes after validation cannot redirect the request. Redirects are returned as
+ * plain 3xx statuses (never followed) and only a bounded prefix of the response body is read.
+ *
+ * @experimental SEP-3415 is a draft; this API may change.
+ */
+export declare const nodeWebhookTransport: WebhookTransport;
+//# sourceMappingURL=webhook-transport.d.ts.map

package/dist/server/events/webhook-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-transport.d.ts","sourceRoot":"","sources":["../../../src/server/events/webhook-transport.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAKhE;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,GAAG,CAAC;IACT,wGAAwG;IACxG,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAExG;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,uBAAuB,KAAK,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAErG,qDAAqD;AACrD,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,oBAAoB,CAElE;AAqBD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,gBAkD/B,CAAC"}

package/dist/server/index.d.ts

@@ -1,4 +1,5 @@
 export * from './server.js';
 export * from './types.js';
 export * from './oauth-middleware.js';
+export * from './events/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC"}

package/dist/server/server.d.ts

@@ -1,12 +1,14 @@
 import type * as http from 'node:http';
 import type { Agent, ToolsInput } from '@mastra/core/agent';
 import { MCPServerBase } from '@mastra/core/mcp';
-import type { MCPServerConfig as CoreMCPServerConfig, MCPToolExecutionResultV2, ServerDetailInfo, ServerInfo } from '@mastra/core/mcp';
+import type { MCPServerConfig as CoreMCPServerConfig, MCPServerEventInfo, MCPServerEventsInspector, MCPToolExecutionResultV2, ServerDetailInfo, ServerInfo } from '@mastra/core/mcp';
 import { RequestContext } from '@mastra/core/request-context';
 import type { InternalCoreTool, MCPToolType } from '@mastra/core/tools';
 import type { Workflow } from '@mastra/core/workflows';
 import type { Resource, jsonSchemaValidator } from '@modelcontextprotocol/server';
 import { ServerPromptActions, ServerResourceActions, ServerToolActions } from './actions.js';
+import { ServerEventActions } from './events/actions.js';
+import type { MCPServerEventDefinition, MCPServerEventsOptions } from './events/types.js';
 import type { AppResources, MCPServerCacheHints, MCPServerHTTPRequestOptions, MCPServerPrompts, MCPServerRequestStateOptions, MCPServerResources } from './types.js';
 export interface MCPServerConfig extends CoreMCPServerConfig {
     resources?: MCPServerResources;
@@ -18,6 +20,19 @@ export interface MCPServerConfig extends CoreMCPServerConfig {
     cacheHints?: MCPServerCacheHints;
     /** Integrity protection for `input_required` continuation state. */
     requestState?: MCPServerRequestStateOptions;
+    /**
+     * Event types served over the MCP Events extension (`events/list`, `events/poll`,
+     * `events/stream`), keyed by event name. Declare each with `defineEvent()`.
+     *
+     * @experimental SEP-3415 is a draft; this API may change.
+     */
+    events?: Record<string, MCPServerEventDefinition>;
+    /**
+     * Server-wide settings for `events`.
+     *
+     * @experimental SEP-3415 is a draft; this API may change.
+     */
+    eventsOptions?: MCPServerEventsOptions;
 }
 export interface MCPServerHTTPOptions {
     url: URL;
@@ -69,6 +84,13 @@ export declare class MCPServer extends MCPServerBase {
     readonly resources: ServerResourceActions;
     readonly prompts: ServerPromptActions;
     readonly toolActions: ServerToolActions;
+    /**
+     * Publishes occurrences of the configured `events` to poll, push and (when
+     * `eventsOptions.webhook` is set) webhook subscribers.
+     *
+     * @experimental SEP-3415 is a draft; this API may change.
+     */
+    readonly events: ServerEventActions;
     private readonly resourceOptions?;
     private readonly promptOptions?;
     private readonly appResourceList;
@@ -78,6 +100,10 @@ export declare class MCPServer extends MCPServerBase {
     private readonly mapAuthInfoToUser?;
     private readonly fga?;
     private readonly requestStateCodec;
+    private readonly eventRegistry;
+    private readonly eventsOptions;
+    private eventsInspector;
+    private readonly webhooks?;
     private httpHandler?;
     private nodeHandler?;
     private stdioHandle?;
@@ -120,7 +146,19 @@ export declare class MCPServer extends MCPServerBase {
     private toMCPTool;
     private hasUiMetadata;
     private capabilities;
+    /**
+     * Settings advertised under `extensions["io.modelcontextprotocol/events"]`. `listChanged` is not
+     * advertised: the SDK's `subscriptions/listen` drops the `eventsListChanged` filter, so
+     * `notifications/events/list_changed` cannot be delivered.
+     */
+    private eventsCapability;
     private createServerInstance;
+    /**
+     * {@link setTracedHandler} for methods outside the spec's request map (the events
+     * extension): the request runs under an `MCP_SERVER_REQUEST` span with its resolved
+     * request context. A push stream's span lasts as long as the stream.
+     */
+    private traceCustomRequest;
     /**
      * Registers `method` under an `MCP_SERVER_REQUEST` span, so every request the
      * server answers is recorded — including the list and read methods that never
@@ -193,6 +231,20 @@ export declare class MCPServer extends MCPServerBase {
     listResources(): Promise<{
         resources: Resource[];
     }>;
+    /**
+     * The declared event types as Studio shows them, or `undefined` when the server has none.
+     * @experimental
+     */
+    getEventsInfo(): {
+        events: MCPServerEventInfo[];
+    } | undefined;
+    /**
+     * Polls, streams and test-emits events in-process through the `events/poll` and
+     * `events/stream` code paths, or `undefined` when the server has none. Used by Studio.
+     * @experimental
+     */
+    getEventsInspector(): MCPServerEventsInspector | undefined;
+    private eventsDeps;
 }
 export { ServerPromptActions, ServerResourceActions, ServerToolActions };
 //# sourceMappingURL=server.d.ts.map

package/dist/server/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server/server.ts"],"names":[],"mappings":"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"}

package/dist/shared/events/index.d.ts

@@ -2,4 +2,6 @@ export * from './constants.js';
 export * from './schemas.js';
 export * from './capability.js';
 export type * from './types.js';
+export * from './webhook.js';
+export * from './webhook-url.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/shared/events/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/events/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,mBAAmB,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/events/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,mBAAmB,SAAS,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC"}

package/dist/shared/events/webhook-url.d.ts

@@ -0,0 +1,59 @@
+/** @experimental SEP-3415 is a draft; this API may change. */
+export type WebhookUrlFailure = 'invalid_url' | 'insecure_scheme' | 'disallowed_address' | 'dns_failure';
+/**
+ * Thrown when a callback URL fails the webhook URL policy.
+ *
+ * @experimental SEP-3415 is a draft; this API may change.
+ */
+export declare class WebhookUrlError extends Error {
+    readonly reason: WebhookUrlFailure;
+    readonly url: string;
+    constructor(reason: WebhookUrlFailure, url: string, message: string);
+}
+/** @experimental SEP-3415 is a draft; this API may change. */
+export type WebhookLookup = (hostname: string) => Promise<Array<{
+    address: string;
+    family: 4 | 6;
+}>>;
+/** @experimental SEP-3415 is a draft; this API may change. */
+export interface WebhookUrlPolicyOptions {
+    /** Skip address classification, allowing private and loopback targets (tests and private deployments). */
+    allowPrivate?: boolean;
+    /** Allow `http:` callback URLs. */
+    allowInsecure?: boolean;
+    /** Resolver used for hostnames. Defaults to `dns.promises.lookup` returning every address. */
+    lookup?: WebhookLookup;
+}
+/** @experimental SEP-3415 is a draft; this API may change. */
+export interface ResolvedWebhookUrl {
+    url: URL;
+    /** The validated IP that delivery must connect to, so a later DNS answer cannot rebind it. */
+    address: string;
+    family: 4 | 6;
+}
+/**
+ * True when a literal IP address is globally routable. Non-IP input, scoped (zone) addresses, and
+ * NAT64 / 6to4 addresses that embed a non-global IPv4 address are all treated as not routable.
+ *
+ * @experimental SEP-3415 is a draft; this API may change.
+ */
+export declare function isGloballyRoutableAddress(ip: string): boolean;
+/**
+ * Synchronously validate a callback URL: it must parse, use `https:` (unless `allowInsecure`), carry no
+ * credentials, and, when its host is an IP literal, that IP must be globally routable (unless `allowPrivate`).
+ * Hostnames are not resolved here; use {@link resolveAndValidate} before connecting.
+ *
+ * @throws {WebhookUrlError}
+ * @experimental SEP-3415 is a draft; this API may change.
+ */
+export declare function validateWebhookUrl(url: string, opts?: WebhookUrlPolicyOptions): URL;
+/**
+ * Validate a callback URL and resolve it to the IP that delivery must connect to. Every resolved address
+ * must be globally routable (a mixed answer is a DNS-rebinding vector); the first is returned as the pinned
+ * address. Delivery connects to that address and uses the URL hostname for TLS SNI and the Host header.
+ *
+ * @throws {WebhookUrlError}
+ * @experimental SEP-3415 is a draft; this API may change.
+ */
+export declare function resolveAndValidate(url: string, opts?: WebhookUrlPolicyOptions): Promise<ResolvedWebhookUrl>;
+//# sourceMappingURL=webhook-url.d.ts.map

package/dist/shared/events/webhook-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-url.d.ts","sourceRoot":"","sources":["../../../src/shared/events/webhook-url.ts"],"names":[],"mappings":"AAQA,8DAA8D;AAC9D,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,iBAAiB,GAAG,oBAAoB,GAAG,aAAa,CAAC;AAEzG;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,YAAY,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAKlE;CACF;AAED,8DAA8D;AAC9D,MAAM,MAAM,aAAa,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAA;CAAE,CAAC,CAAC,CAAC;AAErG,8DAA8D;AAC9D,MAAM,WAAW,uBAAuB;IACtC,0GAA0G;IAC1G,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,mCAAmC;IACnC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,8FAA8F;IAC9F,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,8DAA8D;AAC9D,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,GAAG,CAAC;IACT,8FAA8F;IAC9F,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC;CACf;AAqED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAyB7D;AAOD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,uBAA4B,GAAG,GAAG,CAyBvF;AAOD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,uBAA4B,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA6BrH"}