@ai-sdk/mcp 2.0.0-beta.6 → 2.0.0-beta.66

package/src/tool/oauth.ts

@@ -1,17 +1,17 @@
 import pkceChallenge from 'pkce-challenge';
 import {
-  OAuthTokens,
-  OAuthProtectedResourceMetadata,
   OAuthProtectedResourceMetadataSchema,
   OAuthMetadataSchema,
   OpenIdProviderDiscoveryMetadataSchema,
-  AuthorizationServerMetadata,
-  OAuthClientInformation,
   OAuthTokensSchema,
   OAuthErrorResponseSchema,
-  OAuthClientMetadata,
-  OAuthClientInformationFull,
   OAuthClientInformationFullSchema,
+  type OAuthTokens,
+  type OAuthProtectedResourceMetadata,
+  type AuthorizationServerMetadata,
+  type OAuthClientInformation,
+  type OAuthClientMetadata,
+  type OAuthClientInformationFull,
 } from './oauth-types';
 import {
   MCPClientOAuthError,
@@ -24,12 +24,17 @@ import {
 import {
   resourceUrlFromServerUrl,
   checkResourceAllowed,
+  resourceUrlStripSlash,
 } from '../util/oauth-util';
 import { LATEST_PROTOCOL_VERSION } from './types';
-import { FetchFunction } from '@ai-sdk/provider-utils';
-
+import { parseJSON, type FetchFunction } from '@ai-sdk/provider-utils';
 export type AuthResult = 'AUTHORIZED' | 'REDIRECT';
 
+export interface OAuthAuthorizationServerInformation {
+  authorizationServerUrl: string;
+  tokenEndpoint: string;
+}
+
 export interface OAuthClientProvider {
   /**
    * Returns current access token if present; undefined otherwise.
@@ -82,6 +87,21 @@ export interface OAuthClientProvider {
   saveClientInformation?(
     clientInformation: OAuthClientInformation,
   ): void | Promise<void>;
+  authorizationServerInformation?():
+    | OAuthAuthorizationServerInformation
+    | undefined
+    | Promise<OAuthAuthorizationServerInformation | undefined>;
+  saveAuthorizationServerInformation?(
+    authorizationServerInformation: OAuthAuthorizationServerInformation,
+  ): void | Promise<void>;
+  /**
+   * Validates an authorization server URL discovered from MCP protected resource
+   * metadata before the client fetches its OAuth metadata.
+   */
+  validateAuthorizationServerURL?(
+    serverUrl: string | URL,
+    authorizationServerUrl: string | URL,
+  ): void | Promise<void>;
   state?(): string | Promise<string>;
   saveState?(state: string): void | Promise<void>;
   storedState?(): string | undefined | Promise<string | undefined>;
@@ -98,6 +118,158 @@ export class UnauthorizedError extends Error {
   }
 }
 
+function normalizeUrl(url: string | URL): string {
+  return new URL(url).href;
+}
+
+function createAuthorizationServerInformation(
+  authorizationServerUrl: string | URL,
+  metadata?: AuthorizationServerMetadata,
+): OAuthAuthorizationServerInformation {
+  return {
+    authorizationServerUrl: normalizeUrl(authorizationServerUrl),
+    tokenEndpoint: normalizeUrl(
+      metadata?.token_endpoint
+        ? new URL(metadata.token_endpoint)
+        : new URL('/token', authorizationServerUrl),
+    ),
+  };
+}
+
+function addAuthorizationServerInformationToTokens(
+  tokens: OAuthTokens,
+  authorizationServerInformation: OAuthAuthorizationServerInformation,
+): OAuthTokens {
+  return {
+    ...tokens,
+    authorization_server: authorizationServerInformation.authorizationServerUrl,
+    token_endpoint: authorizationServerInformation.tokenEndpoint,
+  };
+}
+
+function addAuthorizationServerInformationToClientInformation<
+  CLIENT_INFORMATION extends OAuthClientInformation,
+>(
+  clientInformation: CLIENT_INFORMATION,
+  authorizationServerInformation: OAuthAuthorizationServerInformation,
+): CLIENT_INFORMATION {
+  return {
+    ...clientInformation,
+    authorization_server: authorizationServerInformation.authorizationServerUrl,
+    token_endpoint: authorizationServerInformation.tokenEndpoint,
+  };
+}
+
+function getAuthorizationServerInformationFromCredentials(credentials?: {
+  authorization_server?: string;
+  token_endpoint?: string;
+}): OAuthAuthorizationServerInformation | undefined {
+  if (!credentials?.authorization_server || !credentials.token_endpoint) {
+    return undefined;
+  }
+
+  return {
+    authorizationServerUrl: normalizeUrl(credentials.authorization_server),
+    tokenEndpoint: normalizeUrl(credentials.token_endpoint),
+  };
+}
+
+async function getStoredAuthorizationServerInformation({
+  provider,
+  clientInformation,
+  tokens,
+}: {
+  provider: OAuthClientProvider;
+  clientInformation: OAuthClientInformation;
+  tokens?: OAuthTokens;
+}): Promise<OAuthAuthorizationServerInformation | undefined> {
+  const tokenAuthorizationServerInformation =
+    getAuthorizationServerInformationFromCredentials(tokens);
+  if (tokenAuthorizationServerInformation) {
+    return tokenAuthorizationServerInformation;
+  }
+
+  const providerAuthorizationServerInformation =
+    await provider.authorizationServerInformation?.();
+  if (providerAuthorizationServerInformation) {
+    return {
+      authorizationServerUrl: normalizeUrl(
+        providerAuthorizationServerInformation.authorizationServerUrl,
+      ),
+      tokenEndpoint: normalizeUrl(
+        providerAuthorizationServerInformation.tokenEndpoint,
+      ),
+    };
+  }
+
+  return getAuthorizationServerInformationFromCredentials(clientInformation);
+}
+
+async function saveAuthorizationServerInformation({
+  provider,
+  clientInformation,
+  authorizationServerInformation,
+}: {
+  provider: OAuthClientProvider;
+  clientInformation: OAuthClientInformation;
+  authorizationServerInformation: OAuthAuthorizationServerInformation;
+}): Promise<boolean> {
+  if (provider.saveAuthorizationServerInformation) {
+    await provider.saveAuthorizationServerInformation(
+      authorizationServerInformation,
+    );
+    return true;
+  }
+
+  if (provider.saveClientInformation) {
+    await provider.saveClientInformation(
+      addAuthorizationServerInformationToClientInformation(
+        clientInformation,
+        authorizationServerInformation,
+      ),
+    );
+    return true;
+  }
+
+  return false;
+}
+
+function assertResourceMetadataUrlSameOrigin(
+  serverUrl: string | URL,
+  resourceMetadataUrl?: URL,
+): void {
+  if (!resourceMetadataUrl) {
+    return;
+  }
+
+  const expectedOrigin = new URL(serverUrl).origin;
+  if (resourceMetadataUrl.origin !== expectedOrigin) {
+    throw new MCPClientOAuthError({
+      message: `OAuth protected resource metadata URL ${resourceMetadataUrl.href} must have the same origin as the MCP server URL ${expectedOrigin}`,
+    });
+  }
+}
+
+function assertAuthorizationServerInformationMatches({
+  storedAuthorizationServerInformation,
+  currentAuthorizationServerInformation,
+}: {
+  storedAuthorizationServerInformation: OAuthAuthorizationServerInformation;
+  currentAuthorizationServerInformation: OAuthAuthorizationServerInformation;
+}): void {
+  if (
+    storedAuthorizationServerInformation.authorizationServerUrl !==
+      currentAuthorizationServerInformation.authorizationServerUrl ||
+    storedAuthorizationServerInformation.tokenEndpoint !==
+      currentAuthorizationServerInformation.tokenEndpoint
+  ) {
+    throw new MCPClientOAuthError({
+      message:
+        'OAuth authorization server metadata does not match the metadata that issued the stored credentials',
+    });
+  }
+}
+
 /**
  * Extracts the OAuth 2.0 Protected Resource Metadata URL from a WWW-Authenticate header (RFC9728).
  * Looks for a resource="..." parameter.
@@ -270,23 +442,30 @@ export async function discoverOAuthProtectedResourceMetadata(
  */
 export function buildDiscoveryUrls(
   authorizationServerUrl: string | URL,
-): { url: URL; type: 'oauth' | 'oidc' }[] {
+): { url: URL; type: 'oauth' | 'oidc'; expectedIssuer: string }[] {
   const url =
     typeof authorizationServerUrl === 'string'
       ? new URL(authorizationServerUrl)
       : authorizationServerUrl;
   const hasPath = url.pathname !== '/';
-  const urlsToTry: { url: URL; type: 'oauth' | 'oidc' }[] = [];
+  const rootIssuer = url.origin;
+  const urlsToTry: {
+    url: URL;
+    type: 'oauth' | 'oidc';
+    expectedIssuer: string;
+  }[] = [];
 
   if (!hasPath) {
     urlsToTry.push({
       url: new URL('/.well-known/oauth-authorization-server', url.origin),
       type: 'oauth',
+      expectedIssuer: rootIssuer,
     });
 
     urlsToTry.push({
       url: new URL('/.well-known/openid-configuration', url.origin),
       type: 'oidc',
+      expectedIssuer: rootIssuer,
     });
 
     return urlsToTry;
@@ -296,6 +475,7 @@ export function buildDiscoveryUrls(
   if (pathname.endsWith('/')) {
     pathname = pathname.slice(0, -1);
   }
+  const pathIssuer = `${url.origin}${pathname}`;
 
   urlsToTry.push({
     url: new URL(
@@ -303,26 +483,41 @@ export function buildDiscoveryUrls(
       url.origin,
     ),
     type: 'oauth',
+    expectedIssuer: pathIssuer,
   });
 
   urlsToTry.push({
     url: new URL('/.well-known/oauth-authorization-server', url.origin),
     type: 'oauth',
+    expectedIssuer: rootIssuer,
   });
 
   urlsToTry.push({
     url: new URL(`/.well-known/openid-configuration${pathname}`, url.origin),
     type: 'oidc',
+    expectedIssuer: pathIssuer,
   });
 
   urlsToTry.push({
     url: new URL(`${pathname}/.well-known/openid-configuration`, url.origin),
     type: 'oidc',
+    expectedIssuer: pathIssuer,
   });
 
   return urlsToTry;
 }
 
+function assertMetadataIssuerMatches(
+  metadata: AuthorizationServerMetadata,
+  expectedIssuer: string,
+): void {
+  if (metadata.issuer !== expectedIssuer) {
+    throw new MCPClientOAuthError({
+      message: `OAuth authorization server metadata issuer ${metadata.issuer} does not match expected issuer ${expectedIssuer}`,
+    });
+  }
+}
+
 export async function discoverAuthorizationServerMetadata(
   authorizationServerUrl: string | URL,
   {
@@ -337,7 +532,7 @@ export async function discoverAuthorizationServerMetadata(
 
   const urlsToTry = buildDiscoveryUrls(authorizationServerUrl);
 
-  for (const { url: endpointUrl, type } of urlsToTry) {
+  for (const { url: endpointUrl, type, expectedIssuer } of urlsToTry) {
     const response = await fetchWithCorsRetry(endpointUrl, headers, fetchFn);
 
     if (!response) {
@@ -359,11 +554,14 @@ export async function discoverAuthorizationServerMetadata(
     }
 
     if (type === 'oauth') {
-      return OAuthMetadataSchema.parse(await response.json());
+      const metadata = OAuthMetadataSchema.parse(await response.json());
+      assertMetadataIssuerMatches(metadata, expectedIssuer);
+      return metadata;
     } else {
       const metadata = OpenIdProviderDiscoveryMetadataSchema.parse(
         await response.json(),
       );
+      assertMetadataIssuerMatches(metadata, expectedIssuer);
 
       // MCP spec requires OIDC providers to support S256 PKCE
       if (!metadata.code_challenge_methods_supported?.includes('S256')) {
@@ -451,7 +649,10 @@ export async function startAuthorization(
   }
 
   if (resource) {
-    authorizationUrl.searchParams.set('resource', resource.href);
+    authorizationUrl.searchParams.set(
+      'resource',
+      resourceUrlStripSlash(resource),
+    );
   }
 
   return { authorizationUrl, codeVerifier };
@@ -587,7 +788,9 @@ export async function parseErrorResponse(
   const body = input instanceof Response ? await input.text() : input;
 
   try {
-    const result = OAuthErrorResponseSchema.parse(JSON.parse(body));
+    const result = OAuthErrorResponseSchema.parse(
+      await parseJSON({ text: body }),
+    );
     const { error, error_description, error_uri } = result;
     const errorClass = OAUTH_ERRORS[error] || ServerError;
     return new errorClass({
@@ -662,7 +865,12 @@ export async function exchangeAuthorization(
   });
 
   if (addClientAuthentication) {
-    addClientAuthentication(headers, params, authorizationServerUrl, metadata);
+    await addClientAuthentication(
+      headers,
+      params,
+      authorizationServerUrl,
+      metadata,
+    );
   } else {
     const supportedMethods =
       metadata?.token_endpoint_auth_methods_supported ?? [];
@@ -675,7 +883,7 @@ export async function exchangeAuthorization(
   }
 
   if (resource) {
-    params.set('resource', resource.href);
+    params.set('resource', resourceUrlStripSlash(resource));
   }
 
   const response = await (fetchFn ?? fetch)(tokenUrl, {
@@ -749,7 +957,12 @@ export async function refreshAuthorization(
   });
 
   if (addClientAuthentication) {
-    addClientAuthentication(headers, params, authorizationServerUrl, metadata);
+    await addClientAuthentication(
+      headers,
+      params,
+      authorizationServerUrl,
+      metadata,
+    );
   } else {
     const supportedMethods =
       metadata?.token_endpoint_auth_methods_supported ?? [];
@@ -762,7 +975,7 @@ export async function refreshAuthorization(
   }
 
   if (resource) {
-    params.set('resource', resource.href);
+    params.set('resource', resourceUrlStripSlash(resource));
   }
 
   const response = await (fetchFn ?? fetch)(tokenUrl, {
@@ -904,6 +1117,11 @@ async function authInternal(
 ): Promise<AuthResult> {
   let resourceMetadata: OAuthProtectedResourceMetadata | undefined;
   let authorizationServerUrl: string | URL | undefined;
+
+  /** Reject Protected Resource Metadata URLs outside the configured MCP server origin. */
+  assertResourceMetadataUrlSameOrigin(serverUrl, resourceMetadataUrl);
+
+  /** Discover PRM and select its advertised authorization server. */
   try {
     resourceMetadata = await discoverOAuthProtectedResourceMetadata(
       serverUrl,
@@ -918,27 +1136,35 @@ async function authInternal(
     }
   } catch {}
 
-  /**
-   * If we don't get a valid authorization server metadata from protected resource metadata,
-   * fallback to the legacy MCP spec's implementation (version 2025-03-26): MCP server acts as the Authorization server.
-   */
+  /** Fall back to legacy MCP behavior where the MCP server is the Authorization Server */
   if (!authorizationServerUrl) {
     authorizationServerUrl = serverUrl;
   }
 
+  /** Validate and select the resource value sent to the AS */
   const resource: URL | undefined = await selectResourceURL(
     serverUrl,
     provider,
     resourceMetadata,
   );
 
+  /** Let applications constrain discovered AS URLs before metadata fetches. */
+  await provider.validateAuthorizationServerURL?.(
+    serverUrl,
+    authorizationServerUrl,
+  );
+
+  /** Discover AS metadata and derive the credential pin for this flow */
   const metadata = await discoverAuthorizationServerMetadata(
     authorizationServerUrl,
     {
       fetchFn,
     },
   );
+  const currentAuthorizationServerInformation =
+    createAuthorizationServerInformation(authorizationServerUrl, metadata);
 
+  /** Load or register client credentials with the AS pin attached. */
   let clientInformation = await Promise.resolve(provider.clientInformation());
   if (!clientInformation) {
     if (authorizationCode !== undefined) {
@@ -959,11 +1185,14 @@ async function authInternal(
       fetchFn,
     });
 
-    await provider.saveClientInformation(fullInformation);
-    clientInformation = fullInformation;
+    clientInformation = addAuthorizationServerInformationToClientInformation(
+      fullInformation,
+      currentAuthorizationServerInformation,
+    );
+    await provider.saveClientInformation(clientInformation);
   }
 
-  // Exchange authorization code for tokens
+  /** On callback, validate state and AS pin before code exchange */
   if (authorizationCode !== undefined) {
     if (provider.storedState) {
       const expectedState = await provider.storedState();
@@ -974,6 +1203,22 @@ async function authInternal(
       }
     }
 
+    const storedAuthorizationServerInformation =
+      await getStoredAuthorizationServerInformation({
+        provider,
+        clientInformation,
+      });
+    if (!storedAuthorizationServerInformation) {
+      throw new MCPClientOAuthError({
+        message:
+          'Stored OAuth authorization server metadata is required when exchanging an authorization code',
+      });
+    }
+    assertAuthorizationServerInformationMatches({
+      storedAuthorizationServerInformation,
+      currentAuthorizationServerInformation,
+    });
+
     const codeVerifier = await provider.codeVerifier();
     const tokens = await exchangeAuthorization(authorizationServerUrl, {
       metadata,
@@ -986,27 +1231,55 @@ async function authInternal(
       fetchFn: fetchFn,
     });
 
-    await provider.saveTokens(tokens);
+    await provider.saveTokens(
+      addAuthorizationServerInformationToTokens(
+        tokens,
+        currentAuthorizationServerInformation,
+      ),
+    );
     return 'AUTHORIZED';
   }
 
   const tokens = await provider.tokens();
 
-  // Handle token refresh or new authorization
+  /** Refresh only when stored credentials match the current AS pin */
   if (tokens?.refresh_token) {
-    try {
-      // Attempt to refresh the token
-      const newTokens = await refreshAuthorization(authorizationServerUrl, {
-        metadata,
+    const storedAuthorizationServerInformation =
+      await getStoredAuthorizationServerInformation({
+        provider,
         clientInformation,
-        refreshToken: tokens.refresh_token,
-        resource,
-        addClientAuthentication: provider.addClientAuthentication,
-        fetchFn,
+        tokens,
+      });
+
+    if (storedAuthorizationServerInformation) {
+      assertAuthorizationServerInformationMatches({
+        storedAuthorizationServerInformation,
+        currentAuthorizationServerInformation,
       });
+    } else {
+      await provider.invalidateCredentials?.('tokens');
+    }
 
-      await provider.saveTokens(newTokens);
-      return 'AUTHORIZED';
+    try {
+      if (storedAuthorizationServerInformation) {
+        // Attempt to refresh the token
+        const newTokens = await refreshAuthorization(authorizationServerUrl, {
+          metadata,
+          clientInformation,
+          refreshToken: tokens.refresh_token,
+          resource,
+          addClientAuthentication: provider.addClientAuthentication,
+          fetchFn,
+        });
+
+        await provider.saveTokens(
+          addAuthorizationServerInformationToTokens(
+            newTokens,
+            currentAuthorizationServerInformation,
+          ),
+        );
+        return 'AUTHORIZED';
+      }
     } catch (error) {
       if (
         // If this is a ServerError, or an unknown type, log it out and try to continue. Otherwise, escalate so we can fix things and retry.
@@ -1021,6 +1294,7 @@ async function authInternal(
     }
   }
 
+  /** Start authorization and persist the AS pin before redirecting */
   const state = provider.state ? await provider.state() : undefined;
   if (state && provider.saveState) {
     await provider.saveState(state);
@@ -1039,6 +1313,19 @@ async function authInternal(
     },
   );
 
+  const savedAuthorizationServerInformation =
+    await saveAuthorizationServerInformation({
+      provider,
+      clientInformation,
+      authorizationServerInformation: currentAuthorizationServerInformation,
+    });
+  if (!savedAuthorizationServerInformation) {
+    throw new MCPClientOAuthError({
+      message:
+        'OAuth authorization server metadata must be saveable before starting authorization',
+    });
+  }
+
   await provider.saveCodeVerifier(codeVerifier);
   await provider.redirectToAuthorization(authorizationUrl);
   return 'REDIRECT';

package/src/tool/types.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod/v4';
-import { JSONObject } from '@ai-sdk/provider';
-import { FlexibleSchema, Tool } from '@ai-sdk/provider-utils';
+import type { JSONObject } from '@ai-sdk/provider';
+import type { FlexibleSchema, Tool } from '@ai-sdk/provider-utils';
 
 export const LATEST_PROTOCOL_VERSION = '2025-11-25';
 export const SUPPORTED_PROTOCOL_VERSIONS = [
@@ -10,6 +10,13 @@ export const SUPPORTED_PROTOCOL_VERSIONS = [
   '2024-11-05',
 ];
 
+export type McpProviderMetadata = {
+  clientName?: string;
+  title?: string;
+  toolName?: string;
+  app?: JSONObject;
+};
+
 /** MCP tool metadata - keys should follow MCP _meta key format specification */
 const ToolMetaSchema = z.optional(z.record(z.string(), z.unknown()));
 export type ToolMeta = z.infer<typeof ToolMetaSchema>;
@@ -56,8 +63,10 @@ export type McpToolSet<TOOL_SCHEMAS extends ToolSchemas = 'automatic'> =
 const ClientOrServerImplementationSchema = z.looseObject({
   name: z.string(),
   version: z.string(),
+  title: z.optional(z.string()),
 });
 
+// Maps to `Implementation` in the MCP specification
 export type Configuration = z.infer<typeof ClientOrServerImplementationSchema>;
 
 export const BaseParamsSchema = z.looseObject({
@@ -232,10 +241,24 @@ const EmbeddedResourceSchema = z
     resource: z.union([TextResourceContentsSchema, BlobResourceContentsSchema]),
   })
   .loose();
+const ResourceLinkContentSchema = z
+  .object({
+    type: z.literal('resource_link'),
+    uri: z.string(),
+    name: z.string(),
+    description: z.optional(z.string()),
+    mimeType: z.optional(z.string()),
+  })
+  .loose();
 
 export const CallToolResultSchema = ResultSchema.extend({
   content: z.array(
-    z.union([TextContentSchema, ImageContentSchema, EmbeddedResourceSchema]),
+    z.union([
+      TextContentSchema,
+      ImageContentSchema,
+      EmbeddedResourceSchema,
+      ResourceLinkContentSchema,
+    ]),
   ),
   /**
    * @see https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content
@@ -304,6 +327,7 @@ const PromptMessageSchema = z
       TextContentSchema,
       ImageContentSchema,
       EmbeddedResourceSchema,
+      ResourceLinkContentSchema,
     ]),
   })
   .loose();

package/src/util/oauth-util.ts

@@ -14,6 +14,19 @@ export function resourceUrlFromServerUrl(url: URL | string): URL {
   return resourceURL;
 }
 
+/**
+ * Serializes a resource URL to a string, removing the trailing slash that
+ * URL.href adds to pathless URLs. Per the MCP spec, implementations SHOULD
+ * use the form without the trailing slash for better interoperability.
+ */
+export function resourceUrlStripSlash(resource: URL): string {
+  const href = resource.href;
+  if (resource.pathname === '/' && href.endsWith('/')) {
+    return href.slice(0, -1);
+  }
+  return href;
+}
+
 /**
  * Checks if a requested resource URL matches a configured resource URL.
  * A requested resource matches if it has the same scheme, domain, port,