@ai-sdk/mcp 2.0.69 → 2.0.71

package/src/tool/mcp-event-webhook.ts

@@ -0,0 +1,238 @@
+import { safeParseJSON } from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import { MCP_EVENT_CALLBACK_KEY } from './mcp-events';
+import { verifyMCPEventSignature } from './mcp-event-signature';
+import {
+  MCPEventSchema,
+  MCPEventControlSchema,
+  type MCPEvent,
+  type MCPEventControl,
+  type MCPEventDefinition,
+  type MCPEventStore,
+  type MCPEventSubscriptionInfo,
+} from './mcp-event-types';
+
+const MAX_BODY_BYTES = 256 * 1024;
+const VerificationSchema = z.object({
+  type: z.literal('verification'),
+  challenge: z.string().min(1),
+});
+
+export type MCPEventWebhookOptions = {
+  store: MCPEventStore;
+  /**
+   * Optionally validate event data using an application schema or the server's
+   * payloadSchema. Throw to reject the payload with 400 before onEvent runs.
+   * The event envelope and signature are always checked.
+   */
+  validatePayload?: (args: {
+    definition: MCPEventDefinition;
+    data: MCPEvent['data'];
+  }) => void | PromiseLike<void>;
+  /**
+   * Resolve only after durable acceptance or successful processing. Deliveries
+   * may be duplicated or reordered; deduplicate by subscription ID + eventId.
+   * Throw to return 503 so the server can retry. The helper does not run agents.
+   */
+  onEvent: (args: {
+    subscription: MCPEventSubscriptionInfo;
+    event: MCPEvent;
+  }) => Promise<void>;
+  /**
+   * Handles a signed replay gap: some events are no longer available. Reconcile
+   * application state or notify the agent, then resolve after durable acceptance.
+   * The helper saves the fresh cursor and truncated flag; delivery continues.
+   * Throw to return 503 without changing saved state. Deduplicate by subscription
+   * ID + messageId.
+   */
+  onGap?: (args: {
+    subscription: MCPEventSubscriptionInfo;
+    messageId: string;
+    gap: Extract<MCPEventControl, { type: 'gap' }>;
+  }) => Promise<void>;
+  /**
+   * Handles signed termination: the server has ended the subscription. Inspect
+   * termination.error and notify the agent, then resolve after durable acceptance.
+   * The helper removes the saved subscription after this callback succeeds.
+   * Throw to return 503 without changing saved state. Deduplicate by subscription
+   * ID + messageId.
+   */
+  onTerminated?: (args: {
+    subscription: MCPEventSubscriptionInfo;
+    messageId: string;
+    termination: Extract<MCPEventControl, { type: 'terminated' }>;
+  }) => Promise<void>;
+  onError?: (error: unknown) => void;
+};
+
+/**
+ * Create a Web Request/Response handler for MCP webhook deliveries. Mount it
+ * at the callback URL before subscribing. Verification is enabled automatically
+ * using the pending delivery secret saved by the client's subscribe method.
+ */
+export function createMCPEventWebhook({
+  store,
+  validatePayload,
+  onEvent,
+  onGap,
+  onTerminated,
+  onError,
+}: MCPEventWebhookOptions): (request: Request) => Promise<Response> {
+  return async request => {
+    if (request.method !== 'POST') {
+      return new Response(null, { status: 405, headers: { Allow: 'POST' } });
+    }
+    if (
+      request.headers
+        .get('content-type')
+        ?.split(';')[0]
+        .trim()
+        .toLowerCase() !== 'application/json'
+    ) {
+      return new Response(null, { status: 415 });
+    }
+    if (Number(request.headers.get('content-length')) > MAX_BODY_BYTES) {
+      return new Response(null, { status: 413 });
+    }
+
+    try {
+      const key = new URL(request.url).searchParams.get(MCP_EVENT_CALLBACK_KEY);
+      const id = request.headers.get('X-MCP-Subscription-Id');
+      if (!key || !id) return new Response(null, { status: 401 });
+      const subscription = await store.get(key);
+      if (
+        !subscription ||
+        (subscription.id != null && subscription.id !== id)
+      ) {
+        return new Response(null, { status: 401 });
+      }
+
+      // Bound streamed bodies too; Content-Length is optional and untrusted.
+      const reader = request.body?.getReader();
+      if (!reader) return new Response(null, { status: 400 });
+      const chunks: Uint8Array[] = [];
+      let length = 0;
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          length += value.byteLength;
+          if (length > MAX_BODY_BYTES) {
+            await reader.cancel();
+            return new Response(null, { status: 413 });
+          }
+          chunks.push(value);
+        }
+      } finally {
+        reader.releaseLock();
+      }
+      const body = new Uint8Array(length);
+      let offset = 0;
+      for (const chunk of chunks) {
+        body.set(chunk, offset);
+        offset += chunk.length;
+      }
+
+      if (
+        !(await verifyMCPEventSignature({
+          headers: request.headers,
+          body,
+          secret: subscription.delivery.secret,
+        }))
+      ) {
+        return new Response(null, { status: 401 });
+      }
+      const parsed = await safeParseJSON({
+        text: new TextDecoder().decode(body),
+      });
+      if (!parsed.success) return new Response(null, { status: 400 });
+      const value = parsed.value;
+
+      let control: MCPEventControl | undefined;
+      if (value != null && typeof value === 'object' && 'type' in value) {
+        if (value.type === 'verification') {
+          const verification = VerificationSchema.safeParse(value);
+          if (!verification.success) return new Response(null, { status: 400 });
+          return Response.json({ challenge: verification.data.challenge });
+        }
+        const parsedControl = MCPEventControlSchema.safeParse(value);
+        if (!parsedControl.success) return new Response(null, { status: 400 });
+        control = parsedControl.data;
+      }
+
+      // Servers can POST before a subscribe or refresh response is persisted.
+      // Events and gaps must retry until the ID and renewed expiration are saved.
+      // A verified termination for a known ID can end a pending renewal too:
+      // access may have been revoked, so renewal can no longer succeed.
+      if (
+        subscription.id == null ||
+        (subscription.status !== 'active' && control?.type !== 'terminated')
+      )
+        return new Response(null, { status: 503 });
+      const subscriptionInfo: MCPEventSubscriptionInfo = {
+        id: subscription.id,
+        name: subscription.name,
+        arguments: subscription.arguments,
+        delivery: { mode: 'webhook', url: subscription.delivery.url },
+        refreshBefore: subscription.refreshBefore ?? null,
+      };
+      if (control) {
+        const messageId = request.headers.get('webhook-id')!;
+        if (control.type === 'gap') {
+          await onGap?.({
+            subscription: subscriptionInfo,
+            messageId,
+            gap: control,
+          });
+          await store.update(subscription.key, {
+            cursor: control.cursor,
+            truncated: true,
+          });
+        } else {
+          await onTerminated?.({
+            subscription: subscriptionInfo,
+            messageId,
+            termination: control,
+          });
+          await store.delete(subscription.key);
+        }
+        return new Response(null, { status: 204 });
+      }
+      if (
+        subscription.refreshBefore != null &&
+        Date.parse(subscription.refreshBefore) <= Date.now()
+      ) {
+        return new Response(null, { status: 410 });
+      }
+      const event = MCPEventSchema.safeParse(value);
+      if (
+        !event.success ||
+        event.data.name !== subscription.name ||
+        event.data.eventId !== request.headers.get('webhook-id')
+      ) {
+        return new Response(null, { status: 400 });
+      }
+      try {
+        await validatePayload?.({
+          definition: subscription.definition,
+          data: event.data.data,
+        });
+      } catch (error) {
+        onError?.(error);
+        return new Response(null, { status: 400 });
+      }
+
+      await onEvent({
+        subscription: subscriptionInfo,
+        event: event.data,
+      });
+      if (event.data.cursor !== undefined) {
+        await store.update(subscription.key, { cursor: event.data.cursor });
+      }
+      return new Response(null, { status: 204 });
+    } catch (error) {
+      onError?.(error);
+      return new Response(null, { status: 503 });
+    }
+  };
+}

package/src/tool/mcp-events-adapter.ts

@@ -0,0 +1,82 @@
+import type { JSONObject } from '@ai-sdk/provider';
+import type { MCPEvents } from './mcp-event-types';
+import type { RequestOptions } from './types';
+
+/** A durable watch owned by the adapter's backend, not an upstream MCP lease. */
+export type ManagedSubscription = {
+  /** Backend subscription ID; use it for managed lifecycle operations. */
+  id: string;
+  name: string;
+  arguments: JSONObject;
+  status:
+    | 'pending'
+    | 'active'
+    | 'needs_auth'
+    | 'stopped'
+    | 'expired'
+    | 'failed';
+  /** Application monitoring deadline. null means until explicitly stopped. */
+  expiresAt: string | null;
+  cleanupStatus?: 'pending' | 'complete' | 'exhausted';
+};
+
+export type ManagedSubscribeInput = {
+  name: string;
+  arguments: JSONObject;
+  /** Application metadata, not an authorization grant. */
+  context?: JSONObject;
+  /** Reuse the original key when recovering an uncertain create result. */
+  idempotencyKey: string;
+  options?: RequestOptions;
+} & (
+  | { ttlMs: number; expiresAt?: never }
+  | { expiresAt: string | null; ttlMs?: never }
+);
+
+/**
+ * Bound to an authorized account and destination by the application. The backend
+ * owns callback provisioning, verification, persistence, renewal and cleanup.
+ * Implementations must honor request options and preserve actionable errors.
+ * Cancelling a request does not cancel an already accepted remote subscription.
+ */
+export interface MCPEventsAdapter {
+  subscribe(input: ManagedSubscribeInput): Promise<ManagedSubscription>;
+
+  getSubscription(input: {
+    id: string;
+    options?: RequestOptions;
+  }): Promise<ManagedSubscription>;
+
+  listSubscriptions(input?: {
+    cursor?: string;
+    limit?: number;
+    status?: ManagedSubscription['status'];
+    options?: RequestOptions;
+  }): Promise<{
+    subscriptions: ManagedSubscription[];
+    nextCursor?: string;
+  }>;
+
+  unsubscribe(input: {
+    id: string;
+    options?: RequestOptions;
+  }): Promise<ManagedSubscription>;
+}
+
+/** Catalog discovery uses MCP; all subscription operations use the adapter. */
+export interface ManagedMCPEvents extends MCPEventsAdapter {
+  list: MCPEvents['list'];
+}
+
+export function createManagedMCPEvents(
+  adapter: MCPEventsAdapter,
+  list: MCPEvents['list'],
+): ManagedMCPEvents {
+  return {
+    list,
+    subscribe: input => adapter.subscribe(input),
+    getSubscription: input => adapter.getSubscription(input),
+    listSubscriptions: input => adapter.listSubscriptions(input),
+    unsubscribe: input => adapter.unsubscribe(input),
+  };
+}

package/src/tool/mcp-events.ts

@@ -0,0 +1,219 @@
+import { MCPClientError } from '../error/mcp-client-error';
+import {
+  createMCPEventSecret,
+  decodeMCPEventSecret,
+} from './mcp-event-signature';
+import {
+  ListEventsResultSchema,
+  SubscribeEventResultSchema,
+  type MCPEventStore,
+  type MCPEventsConfig,
+  type MCPEvents,
+  type MCPEventSubscription,
+} from './mcp-event-types';
+import { ResultSchema, type Request, type RequestOptions } from './types';
+import type { z } from 'zod/v4';
+
+export const MCP_EVENT_CALLBACK_KEY = 'mcp_event_subscription';
+
+export function createMCPEvents({
+  request,
+  store,
+  validateArguments,
+}: {
+  request: <T extends z.ZodType<object>>(args: {
+    request: Request;
+    resultSchema: T;
+    options?: RequestOptions;
+  }) => Promise<z.infer<T>>;
+  store?: MCPEventStore;
+  validateArguments?: MCPEventsConfig['validateArguments'];
+}): MCPEvents {
+  function getStore(): MCPEventStore {
+    if (!store) {
+      throw new MCPClientError({
+        message:
+          'Configure experimental_events.store to manage direct event subscriptions',
+      });
+    }
+    return store;
+  }
+
+  async function getSubscription({
+    id,
+    key,
+  }: Parameters<MCPEvents['refresh']>[0]): Promise<MCPEventSubscription> {
+    const storage = getStore();
+    const subscription =
+      id !== undefined ? await storage.getById(id) : await storage.get(key);
+    if (!subscription) {
+      throw new MCPClientError({
+        message: `Unknown MCP event subscription: ${id ?? key}`,
+      });
+    }
+    return subscription;
+  }
+
+  async function subscribe(
+    subscription: MCPEventSubscription,
+    options?: RequestOptions,
+  ) {
+    const result = await request({
+      request: {
+        method: 'events/subscribe',
+        params: {
+          name: subscription.name,
+          arguments: subscription.arguments,
+          delivery: subscription.delivery,
+          cursor: subscription.cursor,
+          ...(subscription.ttlMs === undefined
+            ? {}
+            : { ttlMs: subscription.ttlMs }),
+          ...(subscription.maxAgeMs === undefined
+            ? {}
+            : { maxAgeMs: subscription.maxAgeMs }),
+        },
+      },
+      resultSchema: SubscribeEventResultSchema,
+      options,
+    });
+    await getStore().update(subscription.key, {
+      id: result.id,
+      refreshBefore: result.refreshBefore,
+      cursor: result.cursor,
+      truncated: result.truncated,
+      status: 'active',
+    });
+    return result;
+  }
+
+  const events: MCPEvents = {
+    list({ params, options } = {}) {
+      return request({
+        request: { method: 'events/list', params },
+        resultSchema: ListEventsResultSchema,
+        options,
+      });
+    },
+
+    async subscribe({
+      name,
+      arguments: args = {},
+      delivery,
+      cursor = null,
+      ttlMs,
+      maxAgeMs,
+      options,
+    }) {
+      const storage = getStore();
+      const url = new URL(delivery.url);
+      const localHttp =
+        delivery.allowInsecureLocalhost === true &&
+        url.protocol === 'http:' &&
+        (url.hostname === '127.0.0.1' || url.hostname === '[::1]');
+      if (
+        (url.protocol !== 'https:' && !localHttp) ||
+        url.username ||
+        url.password ||
+        url.hash
+      ) {
+        throw new MCPClientError({
+          message:
+            'MCP event callback URLs must use HTTPS without credentials or fragments',
+        });
+      }
+      if (delivery.mode !== 'webhook') {
+        throw new MCPClientError({
+          message: 'Only webhook event delivery is supported',
+        });
+      }
+      if (
+        (ttlMs != null && (!Number.isSafeInteger(ttlMs) || ttlMs <= 0)) ||
+        (maxAgeMs != null && (!Number.isSafeInteger(maxAgeMs) || maxAgeMs < 0))
+      ) {
+        throw new MCPClientError({
+          message: 'Invalid MCP event subscription lifetime or replay age',
+        });
+      }
+
+      let pageCursor: string | undefined;
+      const visited = new Set<string>();
+      let definition;
+      do {
+        const page = await events.list({
+          params: { cursor: pageCursor },
+          options,
+        });
+        definition = page.events.find(event => event.name === name);
+        if (definition) break;
+        pageCursor = page.nextCursor ?? undefined;
+        if (pageCursor != null) {
+          if (visited.has(pageCursor)) {
+            throw new MCPClientError({
+              message: 'Repeated MCP events pagination cursor',
+            });
+          }
+          visited.add(pageCursor);
+        }
+      } while (pageCursor != null);
+      if (!definition) {
+        throw new MCPClientError({ message: `Unknown MCP event: ${name}` });
+      }
+      if (!definition.delivery.includes('webhook')) {
+        throw new MCPClientError({
+          message: `MCP event ${name} does not support webhook delivery`,
+        });
+      }
+      await validateArguments?.({ definition, arguments: args });
+      const secret = delivery.secret ?? createMCPEventSecret();
+      decodeMCPEventSecret(secret);
+
+      // A routing key is available before the server-derived subscription ID.
+      // Persist it and the secret before the server attempts callback verification.
+      const key = crypto.randomUUID();
+      url.searchParams.set(MCP_EVENT_CALLBACK_KEY, key);
+      const subscription: MCPEventSubscription = {
+        key,
+        name,
+        arguments: structuredClone(args),
+        definition,
+        delivery: { mode: 'webhook', url: url.href, secret },
+        cursor,
+        truncated: false,
+        ttlMs,
+        maxAgeMs,
+        status: 'pending',
+      };
+      await storage.set(subscription);
+      // Retain pending state on errors: a timed-out request may have registered
+      // the callback remotely. Recover or unsubscribe using the stored key.
+      return subscribe(subscription, options);
+    },
+
+    async refresh(args) {
+      const subscription = await getSubscription(args);
+      // Deliveries must retry until the renewed expiration is persisted.
+      // Retain pending state on errors, as the server may have renewed already.
+      await getStore().update(subscription.key, { status: 'pending' });
+      return subscribe(subscription, args.options);
+    },
+
+    async unsubscribe(args) {
+      const subscription = await getSubscription(args);
+      await request({
+        request: {
+          method: 'events/unsubscribe',
+          params: {
+            name: subscription.name,
+            arguments: subscription.arguments,
+            delivery: { mode: 'webhook', url: subscription.delivery.url },
+          },
+        },
+        resultSchema: ResultSchema,
+        options: args.options,
+      });
+      await getStore().delete(subscription.key);
+    },
+  };
+  return events;
+}

package/src/tool/oauth.ts

@@ -658,8 +658,12 @@ export function buildDiscoveryUrls(
     expectedIssuer: pathIssuer,
   });
 
+  // Assign the path rather than resolving it as a URL reference: a pathname
+  // beginning with // would otherwise replace the authorization server host.
+  const oidcDiscoveryUrl = new URL(url.origin);
+  oidcDiscoveryUrl.pathname = `${pathname}/.well-known/openid-configuration`;
   urlsToTry.push({
-    url: new URL(`${pathname}/.well-known/openid-configuration`, url.origin),
+    url: oidcDiscoveryUrl,
     type: 'oidc',
     expectedIssuer: pathIssuer,
   });
@@ -697,8 +701,17 @@ export async function discoverAuthorizationServerMetadata(
 ): Promise<AuthorizationServerMetadata | undefined> {
   const headers = { 'MCP-Protocol-Version': protocolVersion };
 
+  const authorizationServerOrigin = new URL(authorizationServerUrl).origin;
   const urlsToTry = buildDiscoveryUrls(authorizationServerUrl);
 
+  // Check all candidates before any request so discovery cannot bypass an
+  // application's authorization server validation by changing the origin.
+  if (urlsToTry.some(({ url }) => url.origin !== authorizationServerOrigin)) {
+    throw new MCPClientOAuthError({
+      message: 'OAuth discovery URL changed authorization-server origin',
+    });
+  }
+
   for (const { url: endpointUrl, type, expectedIssuer } of urlsToTry) {
     const response = await fetchWithCorsRetry(
       endpointUrl,

package/src/tool/types.ts

@@ -116,6 +116,7 @@ const ElicitationCapabilitySchema = z
   .loose();
 
 const ServerCapabilitiesSchema = z.looseObject({
+  events: z.looseObject({ listChanged: z.boolean().nullish() }).nullish(),
   experimental: z.optional(z.object({}).loose()),
   logging: z.optional(z.object({}).loose()),
   completions: z.optional(z.object({}).loose()),