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

package/src/tool/mcp-client.ts

@@ -1,19 +1,19 @@
-import { JSONSchema7, JSONValue } from '@ai-sdk/provider';
+import type { JSONObject, JSONSchema7, JSONValue } from '@ai-sdk/provider';
 import {
   asSchema,
   dynamicTool,
-  FlexibleSchema,
   jsonSchema,
   safeParseJSON,
   safeValidateTypes,
-  Tool,
   tool,
-  ToolExecutionOptions,
-  ToolResultOutput,
+  type FlexibleSchema,
+  type Tool,
+  type ToolExecutionOptions,
+  type ToolResultOutput,
 } from '@ai-sdk/provider-utils';
-import { z } from 'zod/v4';
+import type { z } from 'zod/v4';
 import { MCPClientError } from '../error/mcp-client-error';
-import {
+import type {
   JSONRPCError,
   JSONRPCNotification,
   JSONRPCRequest,
@@ -22,43 +22,45 @@ import {
 import {
   createMcpTransport,
   isCustomMcpTransport,
-  MCPTransport,
-  MCPTransportConfig,
+  type MCPTransport,
+  type MCPTransportConfig,
 } from './mcp-transport';
+import { getMCPAppToolMeta, MCP_APP_MIME_TYPE } from './mcp-apps';
 import {
-  CallToolResult,
   CallToolResultSchema,
-  ClientCapabilities,
-  Configuration as ClientConfiguration,
-  ElicitationRequest,
   ElicitationRequestSchema,
-  ElicitResult,
   ElicitResultSchema,
   InitializeResultSchema,
   LATEST_PROTOCOL_VERSION,
-  ListResourceTemplatesResult,
   ListResourceTemplatesResultSchema,
-  ListResourcesResult,
   ListResourcesResultSchema,
-  ListPromptsResult,
   ListPromptsResultSchema,
-  ListToolsResult,
   ListToolsResultSchema,
-  McpToolSet,
-  Notification,
-  PaginatedRequest,
-  ReadResourceResult,
   ReadResourceResultSchema,
-  GetPromptResult,
   GetPromptResultSchema,
-  Request,
-  RequestOptions,
-  ServerCapabilities,
   SUPPORTED_PROTOCOL_VERSIONS,
-  ToolSchemas,
-  ToolMeta,
+  type CallToolResult,
+  type ClientCapabilities,
+  type Configuration,
+  type Configuration as ClientConfiguration,
+  type ElicitationRequest,
+  type ElicitResult,
+  type ListResourceTemplatesResult,
+  type ListResourcesResult,
+  type ListPromptsResult,
+  type ListToolsResult,
+  type McpToolSet,
+  type Notification,
+  type PaginatedRequest,
+  type ReadResourceResult,
+  type GetPromptResult,
+  type Request,
+  type RequestOptions,
+  type ServerCapabilities,
+  type ToolSchemas,
+  type ToolMeta,
+  type McpProviderMetadata,
 } from './types';
-
 const CLIENT_VERSION = '1.0.0';
 
 function mcpToModelOutput({
@@ -81,9 +83,9 @@ function mcpToModelOutput({
       }
       if (part.type === 'image' && 'data' in part && 'mimeType' in part) {
         return {
-          type: 'image-data' as const,
-          data: part.data as string,
+          type: 'file' as const,
           mediaType: part.mimeType as string,
+          data: { type: 'data' as const, data: part.data as string },
         };
       }
       return { type: 'text' as const, text: JSON.stringify(part) };
@@ -99,6 +101,12 @@ export interface MCPClientConfig {
   /** Optional callback for uncaught errors */
   onUncaughtError?: (error: unknown) => void;
   /** Optional client name, defaults to 'ai-sdk-mcp-client' */
+  clientName?: string;
+  /**
+   * Optional client name, defaults to 'ai-sdk-mcp-client'
+   *
+   * @deprecated Use `clientName` instead.
+   */
   name?: string;
   /** Optional client version, defaults to '1.0.0' */
   version?: string;
@@ -119,6 +127,22 @@ export async function createMCPClient(
 }
 
 export interface MCPClient {
+  /**
+   * Information about the connected MCP server, as reported during initialization.
+   * @see https://modelcontextprotocol.io/specification/2025-11-25/schema#implementation
+   */
+  readonly serverInfo: Configuration;
+
+  /**
+   * Optional instructions provided by the server during the initialize handshake.
+   *
+   * These describe how to use the server and its features, and can be used by clients
+   * to improve LLM interactions (e.g. by including them in the system prompt).
+   *
+   * @see https://modelcontextprotocol.io/specification/2025-11-25/schema#initializeresult
+   */
+  readonly instructions?: string;
+
   tools<TOOL_SCHEMAS extends ToolSchemas = 'automatic'>(options?: {
     schemas?: TOOL_SCHEMAS;
   }): Promise<McpToolSet<TOOL_SCHEMAS>>;
@@ -131,6 +155,15 @@ export interface MCPClient {
     options?: RequestOptions;
   }): Promise<ListToolsResult>;
 
+  /**
+   * Calls a tool on the MCP server.
+   */
+  callTool(args: {
+    name: string;
+    arguments?: Record<string, unknown>;
+    options?: RequestOptions;
+  }): Promise<CallToolResult>;
+
   /**
    * Creates AI SDK tools from tool definitions.
    */
@@ -201,6 +234,8 @@ class DefaultMCPClient implements MCPClient {
     (response: JSONRPCResponse | Error) => void
   > = new Map();
   private serverCapabilities: ServerCapabilities = {};
+  private _serverInfo: Configuration = { name: '', version: '' };
+  private _serverInstructions?: string;
   private isClosed = true;
   private elicitationRequestHandler?: (
     request: ElicitationRequest,
@@ -208,7 +243,8 @@ class DefaultMCPClient implements MCPClient {
 
   constructor({
     transport: transportConfig,
-    name = 'ai-sdk-mcp-client',
+    name,
+    clientName = name ?? 'ai-sdk-mcp-client',
     version = CLIENT_VERSION,
     onUncaughtError,
     capabilities,
@@ -242,11 +278,19 @@ class DefaultMCPClient implements MCPClient {
     };
 
     this.clientInfo = {
-      name,
+      name: clientName,
       version,
     };
   }
 
+  get serverInfo(): Configuration {
+    return this._serverInfo;
+  }
+
+  get instructions(): string | undefined {
+    return this._serverInstructions;
+  }
+
   async init(): Promise<this> {
     try {
       await this.transport.start();
@@ -277,6 +321,13 @@ class DefaultMCPClient implements MCPClient {
       }
 
       this.serverCapabilities = result.capabilities;
+      this._serverInfo = result.serverInfo;
+      if (this.transport.setProtocolVersion) {
+        this.transport.setProtocolVersion(result.protocolVersion);
+      } else {
+        this.transport.protocolVersion = result.protocolVersion;
+      }
+      this._serverInstructions = result.instructions;
 
       // Complete initialization handshake:
       await this.notification({
@@ -413,22 +464,20 @@ class DefaultMCPClient implements MCPClient {
     });
   }
 
-  private async callTool({
+  async callTool({
     name,
-    args,
+    arguments: args = {},
     options,
   }: {
     name: string;
-    args: Record<string, unknown>;
-    options?: ToolExecutionOptions;
+    arguments?: Record<string, unknown>;
+    options?: RequestOptions;
   }): Promise<CallToolResult> {
     try {
       return this.request({
         request: { method: 'tools/call', params: { name, arguments: args } },
         resultSchema: CallToolResultSchema,
-        options: {
-          signal: options?.abortSignal,
-        },
+        options,
       });
     } catch (error) {
       throw error;
@@ -569,20 +618,45 @@ class DefaultMCPClient implements MCPClient {
       _meta,
     } of definitions.tools) {
       const resolvedTitle = title ?? annotations?.title;
-      if (schemas !== 'automatic' && !(name in schemas)) {
+      if (
+        schemas !== 'automatic' &&
+        !Object.prototype.hasOwnProperty.call(schemas, name)
+      ) {
         continue;
       }
 
       const self = this;
       const outputSchema =
         schemas !== 'automatic' ? schemas[name]?.outputSchema : undefined;
+      const appMeta = getMCPAppToolMeta({ _meta });
+      const metadata = {
+        clientName: this.clientInfo.name,
+        toolName: name,
+        ...(resolvedTitle != null ? { title: resolvedTitle } : {}),
+        ...(appMeta?.resourceUri != null
+          ? {
+              app: {
+                ...appMeta,
+                mimeType: MCP_APP_MIME_TYPE,
+              } as JSONObject,
+            }
+          : {}),
+      } satisfies McpProviderMetadata;
 
       const execute = async (
         args: any,
-        options: ToolExecutionOptions,
+        options: ToolExecutionOptions<{}>,
       ): Promise<unknown> => {
         options?.abortSignal?.throwIfAborted();
-        const result = await self.callTool({ name, args, options });
+        const result = await self.callTool({
+          name,
+          arguments: args,
+          options: { signal: options?.abortSignal },
+        });
+
+        if (result.isError) {
+          return result;
+        }
 
         if (outputSchema != null) {
           return self.extractStructuredContent(result, outputSchema, name);
@@ -596,6 +670,7 @@ class DefaultMCPClient implements MCPClient {
           ? dynamicTool({
               description,
               title: resolvedTitle,
+              metadata,
               inputSchema: jsonSchema({
                 ...inputSchema,
                 properties: inputSchema.properties ?? {},
@@ -607,6 +682,7 @@ class DefaultMCPClient implements MCPClient {
           : tool({
               description,
               title: resolvedTitle,
+              metadata,
               inputSchema: schemas[name].inputSchema,
               ...(outputSchema != null ? { outputSchema } : {}),
               execute,
@@ -736,6 +812,15 @@ class DefaultMCPClient implements MCPClient {
 
   private async onRequestMessage(request: JSONRPCRequest): Promise<void> {
     try {
+      if (request.method === 'ping') {
+        await this.transport.send({
+          jsonrpc: '2.0',
+          id: request.id,
+          result: {},
+        });
+        return;
+      }
+
       if (request.method !== 'elicitation/create') {
         await this.transport.send({
           jsonrpc: '2.0',

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

@@ -2,19 +2,29 @@ import {
   EventSourceParserStream,
   withUserAgentSuffix,
   getRuntimeEnvironmentUserAgent,
+  type FetchFunction,
 } from '@ai-sdk/provider-utils';
 import { MCPClientError } from '../error/mcp-client-error';
-import { JSONRPCMessage, JSONRPCMessageSchema } from './json-rpc-message';
-import { MCPTransport } from './mcp-transport';
+import {
+  JSONRPCMessageSchema,
+  parseJSONRPCMessage,
+  type JSONRPCMessage,
+} from './json-rpc-message';
+import type { MCPTransport } from './mcp-transport';
 import { VERSION } from '../version';
 import {
-  OAuthClientProvider,
   extractResourceMetadataUrl,
   UnauthorizedError,
   auth,
+  type AuthResult,
+  type OAuthClientProvider,
 } from './oauth';
 import { LATEST_PROTOCOL_VERSION } from './types';
 
+function isMessageEvent(event: string | undefined): boolean {
+  return event === undefined || event === 'message';
+}
+
 /**
  * HTTP MCP transport implementing the Streamable HTTP style.
  *
@@ -30,6 +40,9 @@ export class HttpMCPTransport implements MCPTransport {
   private resourceMetadataUrl?: URL;
   private sessionId?: string;
   private inboundSseConnection?: { close: () => void };
+  private redirectMode: RequestRedirect;
+  private fetchFn: FetchFunction;
+  private authPromise?: Promise<AuthResult>;
 
   // Inbound SSE resumption and reconnection state
   private lastInboundEventId?: string;
@@ -44,19 +57,30 @@ export class HttpMCPTransport implements MCPTransport {
   onclose?: () => void;
   onerror?: (error: unknown) => void;
   onmessage?: (message: JSONRPCMessage) => void;
+  protocolVersion?: string;
 
   constructor({
     url,
     headers,
     authProvider,
+    redirect = 'error',
+    fetch: fetchFn,
   }: {
     url: string;
     headers?: Record<string, string>;
     authProvider?: OAuthClientProvider;
+    redirect?: 'follow' | 'error';
+    fetch?: FetchFunction;
   }) {
     this.url = new URL(url);
     this.headers = headers;
     this.authProvider = authProvider;
+    this.redirectMode = redirect;
+    this.fetchFn = fetchFn ?? globalThis.fetch;
+  }
+
+  setProtocolVersion(version: string): void {
+    this.protocolVersion = version;
   }
 
   private async commonHeaders(
@@ -65,7 +89,7 @@ export class HttpMCPTransport implements MCPTransport {
     const headers: Record<string, string> = {
       ...this.headers,
       ...base,
-      'mcp-protocol-version': LATEST_PROTOCOL_VERSION,
+      'mcp-protocol-version': this.protocolVersion ?? LATEST_PROTOCOL_VERSION,
     };
 
     if (this.sessionId) {
@@ -86,6 +110,27 @@ export class HttpMCPTransport implements MCPTransport {
     );
   }
 
+  /**
+   * Runs a single OAuth recovery flow for concurrent 401 responses.
+   */
+  private authorizeOnce(resourceMetadataUrl?: URL): Promise<AuthResult> {
+    if (!this.authProvider) {
+      return Promise.resolve('REDIRECT');
+    }
+
+    if (!this.authPromise) {
+      this.authPromise = auth(this.authProvider, {
+        serverUrl: this.url,
+        resourceMetadataUrl,
+        fetchFn: this.fetchFn,
+      }).finally(() => {
+        this.authPromise = undefined;
+      });
+    }
+
+    return this.authPromise;
+  }
+
   async start(): Promise<void> {
     if (this.abortController) {
       throw new MCPClientError({
@@ -107,10 +152,11 @@ export class HttpMCPTransport implements MCPTransport {
         !this.abortController.signal.aborted
       ) {
         const headers = await this.commonHeaders({});
-        await fetch(this.url, {
+        await this.fetchFn(this.url.href, {
           method: 'DELETE',
           headers,
           signal: this.abortController.signal,
+          redirect: this.redirectMode,
         }).catch(() => undefined);
       }
     } catch {}
@@ -132,9 +178,10 @@ export class HttpMCPTransport implements MCPTransport {
           headers,
           body: JSON.stringify(message),
           signal: this.abortController?.signal,
+          redirect: this.redirectMode,
         } satisfies RequestInit;
 
-        const response = await fetch(this.url, init);
+        const response = await this.fetchFn(this.url.href, init);
 
         const sessionId = response.headers.get('mcp-session-id');
         if (sessionId) {
@@ -144,10 +191,7 @@ export class HttpMCPTransport implements MCPTransport {
         if (response.status === 401 && this.authProvider && !triedAuth) {
           this.resourceMetadataUrl = extractResourceMetadataUrl(response);
           try {
-            const result = await auth(this.authProvider, {
-              serverUrl: this.url,
-              resourceMetadataUrl: this.resourceMetadataUrl,
-            });
+            const result = await this.authorizeOnce(this.resourceMetadataUrl);
             if (result !== 'AUTHORIZED') {
               const error = new UnauthorizedError();
               throw error;
@@ -181,6 +225,9 @@ export class HttpMCPTransport implements MCPTransport {
 
           const error = new MCPClientError({
             message: errorMessage,
+            statusCode: response.status,
+            url: this.url.href,
+            responseBody: text ?? undefined,
           });
           this.onerror?.(error);
           throw error;
@@ -197,9 +244,13 @@ export class HttpMCPTransport implements MCPTransport {
         if (contentType.includes('application/json')) {
           const data = await response.json();
           const messages: JSONRPCMessage[] = Array.isArray(data)
-            ? data.map((m: unknown) => JSONRPCMessageSchema.parse(m))
+            ? data.map((message: unknown) =>
+                JSONRPCMessageSchema.parse(message),
+              )
             : [JSONRPCMessageSchema.parse(data)];
-          for (const m of messages) this.onmessage?.(m);
+          for (const jsonRpcMessage of messages) {
+            this.onmessage?.(jsonRpcMessage);
+          }
           return;
         }
 
@@ -208,6 +259,8 @@ export class HttpMCPTransport implements MCPTransport {
             const error = new MCPClientError({
               message:
                 'MCP HTTP Transport Error: text/event-stream response without body',
+              statusCode: response.status,
+              url: this.url.href,
             });
             this.onerror?.(error);
             throw error;
@@ -224,10 +277,10 @@ export class HttpMCPTransport implements MCPTransport {
                 const { done, value } = await reader.read();
                 if (done) return;
                 const { event, data } = value;
-                if (event === 'message') {
+                if (isMessageEvent(event)) {
                   try {
-                    const msg = JSONRPCMessageSchema.parse(JSON.parse(data));
-                    this.onmessage?.(msg);
+                    const jsonRpcMessage = await parseJSONRPCMessage(data);
+                    this.onmessage?.(jsonRpcMessage);
                   } catch (error) {
                     const e = new MCPClientError({
                       message:
@@ -252,6 +305,8 @@ export class HttpMCPTransport implements MCPTransport {
 
         const error = new MCPClientError({
           message: `MCP HTTP Transport Error: Unexpected content type: ${contentType}`,
+          statusCode: response.status,
+          url: this.url.href,
         });
         this.onerror?.(error);
         throw error;
@@ -308,10 +363,11 @@ export class HttpMCPTransport implements MCPTransport {
         headers['last-event-id'] = resumeToken;
       }
 
-      const response = await fetch(this.url.href, {
+      const response = await this.fetchFn(this.url.href, {
         method: 'GET',
         headers,
         signal: this.abortController?.signal,
+        redirect: this.redirectMode,
       });
 
       const sessionId = response.headers.get('mcp-session-id');
@@ -322,10 +378,7 @@ export class HttpMCPTransport implements MCPTransport {
       if (response.status === 401 && this.authProvider && !triedAuth) {
         this.resourceMetadataUrl = extractResourceMetadataUrl(response);
         try {
-          const result = await auth(this.authProvider, {
-            serverUrl: this.url,
-            resourceMetadataUrl: this.resourceMetadataUrl,
-          });
+          const result = await this.authorizeOnce(this.resourceMetadataUrl);
           if (result !== 'AUTHORIZED') {
             const error = new UnauthorizedError();
             this.onerror?.(error);
@@ -345,6 +398,8 @@ export class HttpMCPTransport implements MCPTransport {
       if (!response.ok || !response.body) {
         const error = new MCPClientError({
           message: `MCP HTTP Transport Error: GET SSE failed: ${response.status} ${response.statusText}`,
+          statusCode: response.status,
+          url: this.url.href,
         });
         this.onerror?.(error);
         return;
@@ -370,10 +425,10 @@ export class HttpMCPTransport implements MCPTransport {
               this.lastInboundEventId = id;
             }
 
-            if (event === 'message') {
+            if (isMessageEvent(event)) {
               try {
-                const msg = JSONRPCMessageSchema.parse(JSON.parse(data));
-                this.onmessage?.(msg);
+                const jsonRpcMessage = await parseJSONRPCMessage(data);
+                this.onmessage?.(jsonRpcMessage);
               } catch (error) {
                 const e = new MCPClientError({
                   message: 'MCP HTTP Transport Error: Failed to parse message',