@ai-sdk/mcp 2.0.32 → 2.0.33

package/src/tool/mcp-http-transport.ts

@@ -10,7 +10,7 @@ import {
   validateJSONRPCMessage,
   type JSONRPCMessage,
 } from './json-rpc-message';
-import type { MCPTransport } from './mcp-transport';
+import type { MCPTransport, MCPTransportSendOptions } from './mcp-transport';
 import { VERSION } from '../version';
 import {
   extractWWWAuthenticateParams,
@@ -19,7 +19,11 @@ import {
   type AuthResult,
   type OAuthClientProvider,
 } from './oauth';
-import { LATEST_PROTOCOL_VERSION } from './types';
+import {
+  LATEST_LEGACY_PROTOCOL_VERSION,
+  LATEST_PROTOCOL_VERSION,
+} from './types';
+import { encodeMCPHeaderValue } from './mcp-http-headers';
 
 function isMessageEvent(event: string | undefined): boolean {
   return event === undefined || event === 'message';
@@ -33,6 +37,8 @@ function isMessageEvent(event: string | undefined): boolean {
  * for receiving messages.
  */
 export class HttpMCPTransport implements MCPTransport {
+  readonly supportsProtocolVersionDiscovery = true;
+  readonly supportsMcpToolParameterHeaders = true;
   private url: URL;
   private abortController?: AbortController;
   private headers?: Record<string, string>;
@@ -90,7 +96,8 @@ export class HttpMCPTransport implements MCPTransport {
     this.authProvider = authProvider;
     this.redirectMode = redirect;
     this.sessionId = initialSessionId;
-    this.protocolVersion = initialProtocolVersion;
+    this.protocolVersion =
+      initialProtocolVersion ?? LATEST_LEGACY_PROTOCOL_VERSION;
     this.onSessionIdChange = onSessionIdChange;
     this.onSessionExpired = onSessionExpired;
     this.terminateSessionOnClose = terminateSessionOnClose;
@@ -99,6 +106,27 @@ export class HttpMCPTransport implements MCPTransport {
 
   setProtocolVersion(version: string): void {
     this.protocolVersion = version;
+
+    if (!this.abortController) {
+      return;
+    }
+
+    if (this.isModernProtocol()) {
+      this.inboundSseConnection?.close();
+      this.inboundSseConnection = undefined;
+      return;
+    }
+
+    if (!this.inboundSseConnection) {
+      this.startInboundSse();
+    }
+  }
+
+  private isModernProtocol(): boolean {
+    return (
+      (this.protocolVersion ?? LATEST_PROTOCOL_VERSION) ===
+      LATEST_PROTOCOL_VERSION
+    );
   }
 
   private async commonHeaders({
@@ -111,10 +139,11 @@ export class HttpMCPTransport implements MCPTransport {
     const headers: Record<string, string> = {
       ...this.headers,
       ...base,
-      'mcp-protocol-version': this.protocolVersion ?? LATEST_PROTOCOL_VERSION,
+      'mcp-protocol-version':
+        this.protocolVersion ?? LATEST_LEGACY_PROTOCOL_VERSION,
     };
 
-    if (includeSessionId && this.sessionId) {
+    if (!this.isModernProtocol() && includeSessionId && this.sessionId) {
       headers['mcp-session-id'] = this.sessionId;
     }
 
@@ -142,6 +171,10 @@ export class HttpMCPTransport implements MCPTransport {
   }
 
   private applySessionIdFromResponse(response: Response): void {
+    if (this.isModernProtocol()) {
+      return;
+    }
+
     const sessionId = response.headers.get('mcp-session-id');
     if (sessionId) {
       this.setSessionId(sessionId);
@@ -190,7 +223,12 @@ export class HttpMCPTransport implements MCPTransport {
     }
     this.abortController = new AbortController();
 
-    this.startInboundSse();
+    if (
+      this.protocolVersion != null &&
+      this.protocolVersion !== LATEST_PROTOCOL_VERSION
+    ) {
+      this.startInboundSse();
+    }
   }
 
   async close(options?: { signal?: AbortSignal }): Promise<void> {
@@ -199,6 +237,7 @@ export class HttpMCPTransport implements MCPTransport {
 
     try {
       if (
+        !this.isModernProtocol() &&
         this.sessionId &&
         this.terminateSessionOnClose &&
         this.abortController
@@ -220,7 +259,7 @@ export class HttpMCPTransport implements MCPTransport {
 
   async send(
     message: JSONRPCMessage,
-    options?: { signal?: AbortSignal },
+    options?: MCPTransportSendOptions,
   ): Promise<void> {
     options?.signal?.throwIfAborted();
 
@@ -243,6 +282,12 @@ export class HttpMCPTransport implements MCPTransport {
           base: {
             'Content-Type': 'application/json',
             Accept: 'application/json, text/event-stream',
+            ...(this.isModernProtocol() ? options?.headers : {}),
+            ...(this.isModernProtocol() &&
+            'method' in message &&
+            'id' in message
+              ? this.getStandardRequestHeaders(message)
+              : {}),
           },
           includeSessionId: !isInitializeRequest,
         });
@@ -283,7 +328,7 @@ export class HttpMCPTransport implements MCPTransport {
         if (response.status === 202) {
           // If inbound SSE was not available earlier (e.g. 405 before init), try again now
           // Do not await to avoid blocking send()
-          if (!this.inboundSseConnection) {
+          if (!this.isModernProtocol() && !this.inboundSseConnection) {
             this.startInboundSse();
           }
           return;
@@ -291,15 +336,30 @@ export class HttpMCPTransport implements MCPTransport {
 
         if (!response.ok) {
           const text = await response.text().catch(() => null);
+
+          if ('id' in message && text != null) {
+            const jsonRpcMessage = await parseJSONRPCMessage(text).catch(
+              () => undefined,
+            );
+            if (jsonRpcMessage != null && 'error' in jsonRpcMessage) {
+              this.onmessage?.(
+                jsonRpcMessage.id == null
+                  ? { ...jsonRpcMessage, id: message.id }
+                  : jsonRpcMessage,
+              );
+              return;
+            }
+          }
+
           let errorMessage = `MCP HTTP Transport Error: POSTing to endpoint (HTTP ${response.status}): ${text}`;
 
           if (response.status === 404) {
-            if (sessionIdForRequest) {
+            if (!this.isModernProtocol() && sessionIdForRequest) {
               this.expireSessionId(sessionIdForRequest);
 
               errorMessage +=
                 '. The MCP session expired. Create a new client without `initialSessionId` to start a fresh session';
-            } else {
+            } else if (!this.isModernProtocol()) {
               errorMessage +=
                 '. This server does not support HTTP transport. Try using `sse` transport instead';
             }
@@ -413,6 +473,27 @@ export class HttpMCPTransport implements MCPTransport {
     await attempt();
   }
 
+  private getStandardRequestHeaders(
+    message: Extract<JSONRPCMessage, { method: string; id: unknown }>,
+  ): Record<string, string> {
+    const headers: Record<string, string> = {
+      'Mcp-Method': message.method,
+    };
+    const params = message.params;
+    const name =
+      message.method === 'resources/read'
+        ? params?.uri
+        : message.method === 'tools/call' || message.method === 'prompts/get'
+          ? params?.name
+          : undefined;
+
+    if (typeof name === 'string') {
+      headers['Mcp-Name'] = encodeMCPHeaderValue(name);
+    }
+
+    return headers;
+  }
+
   private getNextReconnectionDelay(attempt: number): number {
     const {
       initialReconnectionDelay,
@@ -448,6 +529,10 @@ export class HttpMCPTransport implements MCPTransport {
     triedAuth: boolean = false,
     resumeToken?: string,
   ): void {
+    if (this.isModernProtocol()) {
+      return;
+    }
+
     void this.openInboundSse(triedAuth, resumeToken).catch(error => {
       if (error instanceof Error && error.name === 'AbortError') {
         return;
@@ -461,6 +546,10 @@ export class HttpMCPTransport implements MCPTransport {
     triedAuth: boolean = false,
     resumeToken?: string,
   ): Promise<void> {
+    if (this.isModernProtocol()) {
+      return;
+    }
+
     try {
       const sessionIdForRequest = this.sessionId;
       const headers = await this.commonHeaders({

package/src/tool/mcp-sse-transport.ts

@@ -14,7 +14,7 @@ import {
   auth,
   type OAuthClientProvider,
 } from './oauth';
-import { LATEST_PROTOCOL_VERSION } from './types';
+import { LATEST_LEGACY_PROTOCOL_VERSION } from './types';
 
 function isMessageEvent(event: string | undefined): boolean {
   return event === undefined || event === 'message';
@@ -69,7 +69,8 @@ export class SseMCPTransport implements MCPTransport {
     const headers: Record<string, string> = {
       ...this.headers,
       ...base,
-      'mcp-protocol-version': this.protocolVersion ?? LATEST_PROTOCOL_VERSION,
+      'mcp-protocol-version':
+        this.protocolVersion ?? LATEST_LEGACY_PROTOCOL_VERSION,
     };
 
     if (this.authProvider) {

package/src/tool/mcp-stdio/mcp-stdio-transport.ts

@@ -14,6 +14,7 @@ export interface StdioConfig {
 }
 
 export class StdioMCPTransport implements MCPTransport {
+  readonly supportsProtocolVersionDiscovery = true;
   private process?: ChildProcess;
   private abortController: AbortController = new AbortController();
   private readBuffer: ReadBuffer = new ReadBuffer();

package/src/tool/mcp-transport.ts

@@ -4,6 +4,7 @@ import type { JSONRPCMessage } from './json-rpc-message';
 import { SseMCPTransport } from './mcp-sse-transport';
 import { HttpMCPTransport } from './mcp-http-transport';
 import type { OAuthClientProvider } from './oauth';
+import { LATEST_PROTOCOL_VERSION } from './types';
 
 /**
  * Transport interface for MCP (Model Context Protocol) communication.
@@ -15,6 +16,11 @@ export type MCPTransportSendOptions = {
    */
   signal?: AbortSignal;
 
+  /**
+   * Request-specific HTTP headers produced from MCP tool parameters.
+   */
+  headers?: Record<string, string>;
+
   /**
    * Associates an outgoing message with an incoming request.
    */
@@ -39,6 +45,20 @@ export type MCPTransportCloseOptions = {
 };
 
 export interface MCPTransport {
+  /**
+   * Whether this transport can probe for stateless MCP protocol versions.
+   *
+   * Custom transports default to the legacy initialization flow unless they
+   * explicitly opt in.
+   */
+  supportsProtocolVersionDiscovery?: boolean;
+
+  /**
+   * Whether this transport mirrors x-mcp-header tool parameters into request
+   * headers.
+   */
+  supportsMcpToolParameterHeaders?: boolean;
+
   /**
    * Initialize and start the transport
    */
@@ -161,7 +181,11 @@ export function createMcpTransport(config: MCPTransportConfig): MCPTransport {
     case 'sse':
       return new SseMCPTransport(config);
     case 'http':
-      return new HttpMCPTransport(config);
+      return new HttpMCPTransport({
+        ...config,
+        initialProtocolVersion:
+          config.initialProtocolVersion ?? LATEST_PROTOCOL_VERSION,
+      });
     default:
       throw new MCPClientError({
         message:

package/src/tool/mock-mcp-transport.ts

@@ -2,7 +2,7 @@ import { delay } from '@ai-sdk/provider-utils';
 import type { JSONRPCMessage } from './json-rpc-message';
 import type { MCPTransport } from './mcp-transport';
 import {
-  LATEST_PROTOCOL_VERSION,
+  LATEST_LEGACY_PROTOCOL_VERSION,
   type MCPTool,
   type MCPResource,
   type MCPPrompt,
@@ -163,7 +163,7 @@ export class MockMCPTransport implements MCPTransport {
           jsonrpc: '2.0',
           id: message.id,
           result: this.initializeResult || {
-            protocolVersion: LATEST_PROTOCOL_VERSION,
+            protocolVersion: LATEST_LEGACY_PROTOCOL_VERSION,
             serverInfo: {
               name: 'mock-mcp-server',
               version: '1.0.0',

package/src/tool/oauth-types.ts

@@ -39,6 +39,7 @@ export const OAuthTokensSchema = z
     expires_in: z.number().optional(),
     scope: z.string().optional(),
     refresh_token: z.string().optional(),
+    issuer: SafeUrlSchema.optional(),
     authorization_server: SafeUrlSchema.optional(),
     token_endpoint: SafeUrlSchema.optional(),
   })
@@ -66,6 +67,8 @@ export const OAuthMetadataSchema = z.looseObject({
   authorization_endpoint: SafeUrlSchema,
   token_endpoint: SafeUrlSchema,
   registration_endpoint: SafeUrlSchema.optional(),
+  authorization_response_iss_parameter_supported: z.boolean().optional(),
+  client_id_metadata_document_supported: z.boolean().optional(),
   scopes_supported: z.array(z.string()).optional(),
   response_types_supported: z.array(z.string()),
   grant_types_supported: z.array(z.string()).optional(),
@@ -87,6 +90,8 @@ export const OpenIdProviderMetadataSchema = z.looseObject({
   userinfo_endpoint: SafeUrlSchema.optional(),
   jwks_uri: SafeUrlSchema,
   registration_endpoint: SafeUrlSchema.optional(),
+  authorization_response_iss_parameter_supported: z.boolean().optional(),
+  client_id_metadata_document_supported: z.boolean().optional(),
   scopes_supported: z.array(z.string()).optional(),
   response_types_supported: z.array(z.string()),
   grant_types_supported: z.array(z.string()).optional(),
@@ -114,6 +119,7 @@ export const OAuthClientInformationSchema = z
     client_secret: z.string().optional(),
     client_id_issued_at: z.number().optional(),
     client_secret_expires_at: z.number().optional(),
+    issuer: SafeUrlSchema.optional(),
     authorization_server: SafeUrlSchema.optional(),
     token_endpoint: SafeUrlSchema.optional(),
   })
@@ -122,6 +128,9 @@ export const OAuthClientInformationSchema = z
 export const OAuthClientMetadataSchema = z
   .object({
     redirect_uris: z.array(SafeUrlSchema),
+    application_type: z
+      .union([z.literal('native'), z.literal('web')])
+      .optional(),
     token_endpoint_auth_method: z.string().optional(),
     grant_types: z.array(z.string()).optional(),
     response_types: z.array(z.string()).optional(),

package/src/tool/oauth.ts

@@ -31,6 +31,7 @@ import { parseJSON, type FetchFunction } from '@ai-sdk/provider-utils';
 export type AuthResult = 'AUTHORIZED' | 'REDIRECT';
 
 export interface OAuthAuthorizationServerInformation {
+  issuer?: string;
   authorizationServerUrl: string;
   tokenEndpoint: string;
 }
@@ -122,11 +123,26 @@ function normalizeUrl(url: string | URL): string {
   return new URL(url).href;
 }
 
+function validateAuthorizationResponseIssuer({
+  callbackIssuer,
+  expectedIssuer,
+}: {
+  callbackIssuer: string | undefined;
+  expectedIssuer: string;
+}): void {
+  if (callbackIssuer != null && callbackIssuer !== expectedIssuer) {
+    throw new MCPClientOAuthError({
+      message: `OAuth authorization response issuer ${callbackIssuer} does not match expected issuer ${expectedIssuer}`,
+    });
+  }
+}
+
 function createAuthorizationServerInformation(
   authorizationServerUrl: string | URL,
   metadata?: AuthorizationServerMetadata,
 ): OAuthAuthorizationServerInformation {
   return {
+    issuer: metadata?.issuer ?? String(authorizationServerUrl),
     authorizationServerUrl: normalizeUrl(authorizationServerUrl),
     tokenEndpoint: normalizeUrl(
       metadata?.token_endpoint
@@ -142,6 +158,7 @@ function addAuthorizationServerInformationToTokens(
 ): OAuthTokens {
   return {
     ...tokens,
+    issuer: authorizationServerInformation.issuer,
     authorization_server: authorizationServerInformation.authorizationServerUrl,
     token_endpoint: authorizationServerInformation.tokenEndpoint,
   };
@@ -155,12 +172,14 @@ function addAuthorizationServerInformationToClientInformation<
 ): CLIENT_INFORMATION {
   return {
     ...clientInformation,
+    issuer: authorizationServerInformation.issuer,
     authorization_server: authorizationServerInformation.authorizationServerUrl,
     token_endpoint: authorizationServerInformation.tokenEndpoint,
   };
 }
 
 function getAuthorizationServerInformationFromCredentials(credentials?: {
+  issuer?: string;
   authorization_server?: string;
   token_endpoint?: string;
 }): OAuthAuthorizationServerInformation | undefined {
@@ -169,6 +188,7 @@ function getAuthorizationServerInformationFromCredentials(credentials?: {
   }
 
   return {
+    issuer: credentials.issuer,
     authorizationServerUrl: normalizeUrl(credentials.authorization_server),
     tokenEndpoint: normalizeUrl(credentials.token_endpoint),
   };
@@ -193,6 +213,7 @@ async function getStoredAuthorizationServerInformation({
     await provider.authorizationServerInformation?.();
   if (providerAuthorizationServerInformation) {
     return {
+      issuer: providerAuthorizationServerInformation.issuer,
       authorizationServerUrl: normalizeUrl(
         providerAuthorizationServerInformation.authorizationServerUrl,
       ),
@@ -258,6 +279,10 @@ function assertAuthorizationServerInformationMatches({
   currentAuthorizationServerInformation: OAuthAuthorizationServerInformation;
 }): void {
   if (
+    (storedAuthorizationServerInformation.issuer != null &&
+      currentAuthorizationServerInformation.issuer != null &&
+      storedAuthorizationServerInformation.issuer !==
+        currentAuthorizationServerInformation.issuer) ||
     storedAuthorizationServerInformation.authorizationServerUrl !==
       currentAuthorizationServerInformation.authorizationServerUrl ||
     storedAuthorizationServerInformation.tokenEndpoint !==
@@ -1050,12 +1075,18 @@ export async function registerClient(
     registrationUrl = new URL('/register', authorizationServerUrl);
   }
 
+  const applicationType =
+    clientMetadata.application_type ??
+    inferOAuthApplicationType(clientMetadata.redirect_uris);
   const response = await (fetchFn ?? fetch)(registrationUrl, {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
     },
-    body: JSON.stringify(clientMetadata),
+    body: JSON.stringify({
+      ...clientMetadata,
+      application_type: applicationType,
+    }),
   });
 
   if (!response.ok) {
@@ -1065,12 +1096,32 @@ export async function registerClient(
   return OAuthClientInformationFullSchema.parse(await response.json());
 }
 
+function inferOAuthApplicationType(redirectUris: string[]): 'native' | 'web' {
+  const isNativeRedirectUri = (redirectUri: string): boolean => {
+    const url = new URL(redirectUri);
+    return (
+      ((url.protocol === 'http:' || url.protocol === 'https:') &&
+        (url.hostname === 'localhost' ||
+          url.hostname.endsWith('.localhost') ||
+          url.hostname === '127.0.0.1' ||
+          url.hostname === '[::1]')) ||
+      (url.protocol !== 'http:' && url.protocol !== 'https:')
+    );
+  };
+
+  return redirectUris.every(isNativeRedirectUri) ? 'native' : 'web';
+}
+
 export async function auth(
   provider: OAuthClientProvider,
   options: {
     serverUrl: string | URL;
     authorizationCode?: string;
     callbackState?: string;
+    /**
+     * Value of the `iss` parameter from the authorization response.
+     */
+    callbackIssuer?: string;
     scope?: string;
     resourceMetadataUrl?: URL;
     fetchFn?: FetchFunction;
@@ -1131,6 +1182,7 @@ async function authInternal(
     serverUrl,
     authorizationCode,
     callbackState,
+    callbackIssuer,
     scope,
     resourceMetadataUrl,
     fetchFn,
@@ -1138,6 +1190,7 @@ async function authInternal(
     serverUrl: string | URL;
     authorizationCode?: string;
     callbackState?: string;
+    callbackIssuer?: string;
     scope?: string;
     resourceMetadataUrl?: URL;
     fetchFn?: FetchFunction;
@@ -1194,6 +1247,20 @@ async function authInternal(
 
   /** Load or register client credentials with the AS pin attached. */
   let clientInformation = await Promise.resolve(provider.clientInformation());
+  if (clientInformation?.issuer != null) {
+    const storedAuthorizationServerInformation =
+      await getStoredAuthorizationServerInformation({
+        provider,
+        clientInformation,
+      });
+    if (storedAuthorizationServerInformation) {
+      assertAuthorizationServerInformationMatches({
+        storedAuthorizationServerInformation,
+        currentAuthorizationServerInformation,
+      });
+    }
+  }
+
   if (!clientInformation) {
     if (authorizationCode !== undefined) {
       throw new Error(
@@ -1242,6 +1309,13 @@ async function authInternal(
           'Stored OAuth authorization server metadata is required when exchanging an authorization code',
       });
     }
+    validateAuthorizationResponseIssuer({
+      callbackIssuer,
+      expectedIssuer:
+        storedAuthorizationServerInformation.issuer ??
+        metadata?.issuer ??
+        String(authorizationServerUrl),
+    });
     assertAuthorizationServerInformationMatches({
       storedAuthorizationServerInformation,
       currentAuthorizationServerInformation,

package/src/tool/types.ts

@@ -2,9 +2,11 @@ import { z } from 'zod/v4';
 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 LATEST_PROTOCOL_VERSION = '2026-07-28';
+export const LATEST_LEGACY_PROTOCOL_VERSION = '2025-11-25';
 export const SUPPORTED_PROTOCOL_VERSIONS = [
   LATEST_PROTOCOL_VERSION,
+  LATEST_LEGACY_PROTOCOL_VERSION,
   '2025-06-18',
   '2025-03-26',
   '2024-11-05',
@@ -73,7 +75,9 @@ export const BaseParamsSchema = z.looseObject({
   _meta: z.optional(z.object({}).loose()),
 });
 type BaseParams = z.infer<typeof BaseParamsSchema>;
-export const ResultSchema = BaseParamsSchema;
+export const ResultSchema = BaseParamsSchema.extend({
+  resultType: z.optional(z.string()),
+});
 
 export const RequestSchema = z.object({
   method: z.string(),
@@ -128,6 +132,15 @@ export const ClientCapabilitiesSchema = z
 export type ClientCapabilities = z.infer<typeof ClientCapabilitiesSchema>;
 export type ElicitationCapability = z.infer<typeof ElicitationCapabilitySchema>;
 
+export const DiscoverResultSchema = ResultSchema.extend({
+  supportedVersions: z.array(z.string()),
+  capabilities: ServerCapabilitiesSchema,
+  instructions: z.optional(z.string()),
+  ttlMs: z.optional(z.number()),
+  cacheScope: z.optional(z.union([z.literal('public'), z.literal('private')])),
+});
+export type DiscoverResult = z.infer<typeof DiscoverResultSchema>;
+
 export const InitializeResultSchema = ResultSchema.extend({
   protocolVersion: z.string(),
   capabilities: ServerCapabilitiesSchema,
@@ -154,12 +167,10 @@ const ToolSchema = z
      */
     title: z.optional(z.string()),
     description: z.optional(z.string()),
-    inputSchema: z
-      .object({
-        type: z.literal('object'),
-        properties: z.optional(z.object({}).loose()),
-      })
-      .loose(),
+    inputSchema: z.looseObject({
+      type: z.optional(z.unknown()),
+      properties: z.optional(z.object({}).loose()),
+    }),
     /**
      * @see https://modelcontextprotocol.io/specification/2025-06-18/server/tools#output-schema
      */