@mastra/mcp 0.4.1-alpha.2 → 0.4.1-alpha.4

package/src/client.ts

@@ -5,7 +5,8 @@ import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 import type { SSEClientTransportOptions } from '@modelcontextprotocol/sdk/client/sse.js';
 import { getDefaultEnvironment, StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
-import type { StdioServerParameters } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import type { StreamableHTTPClientTransportOptions } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import { DEFAULT_REQUEST_TIMEOUT_MSEC } from '@modelcontextprotocol/sdk/shared/protocol.js';
 import type { Protocol } from '@modelcontextprotocol/sdk/shared/protocol.js';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
@@ -28,18 +29,43 @@ export interface LogMessage {
 
 export type LogHandler = (logMessage: LogMessage) => void;
 
-// Omit the fields we want to control from the SDK options
-type SSEClientParameters = {
-  url: URL;
-} & SSEClientTransportOptions;
-
-export type MastraMCPServerDefinition = (StdioServerParameters | SSEClientParameters) & {
+// Base options common to all server definitions
+type BaseServerOptions = {
   logger?: LogHandler;
   timeout?: number;
   capabilities?: ClientCapabilities;
   enableServerLogs?: boolean;
 };
 
+type StdioServerDefinition = BaseServerOptions & {
+  command: string; // 'command' is required for Stdio
+  args?: string[];
+  env?: Record<string, string>;
+
+  url?: never; // Exclude 'url' for Stdio
+  requestInit?: never; // Exclude HTTP options for Stdio
+  eventSourceInit?: never; // Exclude HTTP options for Stdio
+  reconnectionOptions?: never; // Exclude Streamable HTTP specific options
+  sessionId?: never; // Exclude Streamable HTTP specific options
+};
+
+// HTTP Server Definition (Streamable HTTP or SSE fallback)
+type HttpServerDefinition = BaseServerOptions & {
+  url: URL; // 'url' is required for HTTP
+
+  command?: never; // Exclude 'command' for HTTP
+  args?: never; // Exclude Stdio options for HTTP
+  env?: never; // Exclude Stdio options for HTTP
+
+  // Include relevant options from SDK HTTP transport types
+  requestInit?: StreamableHTTPClientTransportOptions['requestInit'];
+  eventSourceInit?: SSEClientTransportOptions['eventSourceInit'];
+  reconnectionOptions?: StreamableHTTPClientTransportOptions['reconnectionOptions'];
+  sessionId?: StreamableHTTPClientTransportOptions['sessionId'];
+};
+
+export type MastraMCPServerDefinition = StdioServerDefinition | HttpServerDefinition;
+
 /**
  * Convert an MCP LoggingLevel to a logger method name that exists in our logger
  */
@@ -63,13 +89,15 @@ function convertLogLevelToLoggerMethod(level: LoggingLevel): 'debug' | 'info' |
   }
 }
 
-export class MastraMCPClient extends MastraBase {
+export class InternalMastraMCPClient extends MastraBase {
   name: string;
-  private transport: Transport;
   private client: Client;
   private readonly timeout: number;
   private logHandler?: LogHandler;
   private enableServerLogs?: boolean;
+  private static hasWarned = false;
+  private serverConfig: MastraMCPServerDefinition;
+  private transport?: Transport;
 
   constructor({
     name,
@@ -85,26 +113,18 @@ export class MastraMCPClient extends MastraBase {
     timeout?: number;
   }) {
     super({ name: 'MastraMCPClient' });
+    if (!InternalMastraMCPClient.hasWarned) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[DEPRECATION] MastraMCPClient is deprecated and will be removed in a future release. Please use MCPClient instead.',
+      );
+      InternalMastraMCPClient.hasWarned = true;
+    }
     this.name = name;
     this.timeout = timeout;
     this.logHandler = server.logger;
     this.enableServerLogs = server.enableServerLogs ?? true;
-
-    // Extract log handler from server config to avoid passing it to transport
-    const { logger, enableServerLogs, ...serverConfig } = server;
-
-    if (`url` in serverConfig) {
-      this.transport = new SSEClientTransport(serverConfig.url, {
-        requestInit: serverConfig.requestInit,
-        eventSourceInit: serverConfig.eventSourceInit,
-      });
-    } else {
-      this.transport = new StdioClientTransport({
-        ...serverConfig,
-        // without ...getDefaultEnvironment() commands like npx will fail because there will be no PATH env var
-        env: { ...getDefaultEnvironment(), ...(serverConfig.env || {}) },
-      });
-    }
+    this.serverConfig = server;
 
     this.client = new Client(
       {
@@ -130,14 +150,16 @@ export class MastraMCPClient extends MastraBase {
     // Convert MCP logging level to our logger method
     const loggerMethod = convertLogLevelToLoggerMethod(level);
 
+    const msg = `[${this.name}] ${message}`;
+
     // Log to internal logger
-    this.logger[loggerMethod](message, details);
+    this.logger[loggerMethod](msg, details);
 
     // Send to registered handler if available
     if (this.logHandler) {
       this.logHandler({
         level,
-        message,
+        message: msg,
         timestamp: new Date(),
         serverName: this.name,
         details,
@@ -164,46 +186,135 @@ export class MastraMCPClient extends MastraBase {
     }
   }
 
+  private async connectStdio(command: string) {
+    this.log('debug', `Using Stdio transport for command: ${command}`);
+    try {
+      this.transport = new StdioClientTransport({
+        command,
+        args: this.serverConfig.args,
+        env: { ...getDefaultEnvironment(), ...(this.serverConfig.env || {}) },
+      });
+      await this.client.connect(this.transport, { timeout: this.serverConfig.timeout ?? this.timeout });
+      this.log('debug', `Successfully connected to MCP server via Stdio`);
+    } catch (e) {
+      this.log('error', e instanceof Error ? e.stack || e.message : JSON.stringify(e));
+      throw e;
+    }
+  }
+
+  private async connectHttp(url: URL) {
+    const { requestInit, eventSourceInit } = this.serverConfig;
+
+    this.log('debug', `Attempting to connect to URL: ${url}`);
+
+    // Assume /sse means sse.
+    let shouldTrySSE = url.pathname.endsWith(`/sse`);
+
+    if (!shouldTrySSE) {
+      try {
+        // Try Streamable HTTP transport first
+        this.log('debug', 'Trying Streamable HTTP transport...');
+        const streamableTransport = new StreamableHTTPClientTransport(url, {
+          requestInit,
+          reconnectionOptions: this.serverConfig.reconnectionOptions,
+          sessionId: this.serverConfig.sessionId,
+        });
+        await this.client.connect(streamableTransport, {
+          timeout:
+            // this is hardcoded to 3s because the long default timeout would be extremely slow for sse backwards compat (60s)
+            3000,
+        });
+        this.transport = streamableTransport;
+        this.log('debug', 'Successfully connected using Streamable HTTP transport.');
+      } catch (error) {
+        this.log('debug', `Streamable HTTP transport failed: ${error}`);
+        shouldTrySSE = true;
+      }
+    }
+
+    if (shouldTrySSE) {
+      this.log('debug', 'Falling back to deprecated HTTP+SSE transport...');
+      try {
+        // Fallback to SSE transport
+        const sseTransport = new SSEClientTransport(url, { requestInit, eventSourceInit });
+        await this.client.connect(sseTransport, { timeout: this.serverConfig.timeout ?? this.timeout });
+        this.transport = sseTransport;
+        this.log('debug', 'Successfully connected using deprecated HTTP+SSE transport.');
+      } catch (sseError) {
+        this.log(
+          'error',
+          `Failed to connect with SSE transport after failing to connect to Streamable HTTP transport first. SSE error: ${sseError}`,
+        );
+        throw new Error('Could not connect to server with any available HTTP transport');
+      }
+    }
+  }
+
   private isConnected = false;
 
   async connect() {
     if (this.isConnected) return;
-    try {
-      this.log('debug', `Connecting to MCP server`);
-      await this.client.connect(this.transport, {
-        timeout: this.timeout,
-      });
-      this.isConnected = true;
-      const originalOnClose = this.client.onclose;
-      this.client.onclose = () => {
-        this.log('debug', `MCP server connection closed`);
-        this.isConnected = false;
-        if (typeof originalOnClose === `function`) {
-          originalOnClose();
-        }
-      };
-      asyncExitHook(
-        async () => {
-          this.log('debug', `Disconnecting MCP server during exit`);
-          await this.disconnect();
-        },
-        { wait: 5000 },
-      );
 
-      process.on('SIGTERM', () => gracefulExit());
-      this.log('info', `Successfully connected to MCP server`);
-    } catch (e) {
-      this.log('error', `Failed connecting to MCP server`, {
-        error: e instanceof Error ? e.stack : JSON.stringify(e, null, 2),
-      });
+    const { command, url } = this.serverConfig;
+
+    if (command) {
+      await this.connectStdio(command);
+    } else if (url) {
+      await this.connectHttp(url);
+    } else {
+      throw new Error('Server configuration must include either a command or a url.');
+    }
+
+    this.isConnected = true;
+    const originalOnClose = this.client.onclose;
+    this.client.onclose = () => {
+      this.log('debug', `MCP server connection closed`);
       this.isConnected = false;
-      throw e;
+      if (typeof originalOnClose === `function`) {
+        originalOnClose();
+      }
+    };
+    asyncExitHook(
+      async () => {
+        this.log('debug', `Disconnecting MCP server during exit`);
+        await this.disconnect();
+      },
+      { wait: 5000 },
+    );
+
+    process.on('SIGTERM', () => gracefulExit());
+    this.log('debug', `Successfully connected to MCP server`);
+  }
+
+  /**
+   * Get the current session ID if using the Streamable HTTP transport.
+   * Returns undefined if not connected or not using Streamable HTTP.
+   */
+  get sessionId(): string | undefined {
+    if (this.transport instanceof StreamableHTTPClientTransport) {
+      return this.transport.sessionId;
     }
+    return undefined;
   }
 
   async disconnect() {
+    if (!this.transport) {
+      this.log('debug', 'Disconnect called but no transport was connected.');
+      return;
+    }
     this.log('debug', `Disconnecting from MCP server`);
-    return await this.client.close();
+    try {
+      await this.transport.close();
+      this.log('debug', 'Successfully disconnected from MCP server');
+    } catch (e) {
+      this.log('error', 'Error during MCP server disconnect', {
+        error: e instanceof Error ? e.stack : JSON.stringify(e, null, 2),
+      });
+      throw e;
+    } finally {
+      this.transport = undefined;
+      this.isConnected = false;
+    }
   }
 
   // TODO: do the type magic to return the right method type. Right now we get infinitely deep infered type errors from Zod without using "any"
@@ -259,3 +370,8 @@ export class MastraMCPClient extends MastraBase {
     return toolsRes;
   }
 }
+
+/**
+ * @deprecated MastraMCPClient is deprecated and will be removed in a future release. Please use MCPClient instead.
+ */
+export const MastraMCPClient = InternalMastraMCPClient;

package/src/configuration.test.ts

@@ -1,12 +1,12 @@
 import { spawn } from 'child_process';
 import path from 'path';
 import { describe, it, expect, beforeEach, afterEach, afterAll, beforeAll, vi } from 'vitest';
-import { MCPConfiguration } from './configuration';
+import { MCPClient } from './configuration';
 
 vi.setConfig({ testTimeout: 80000, hookTimeout: 80000 });
 
-describe('MCPConfiguration', () => {
-  let mcp: MCPConfiguration;
+describe('MCPClient', () => {
+  let mcp: MCPClient;
   let weatherProcess: ReturnType<typeof spawn>;
 
   beforeAll(async () => {
@@ -36,7 +36,7 @@ describe('MCPConfiguration', () => {
   });
 
   beforeEach(async () => {
-    mcp = new MCPConfiguration({
+    mcp = new MCPClient({
       servers: {
         stockPrice: {
           command: 'npx',
@@ -95,7 +95,7 @@ describe('MCPConfiguration', () => {
   });
 
   it('should handle connection errors gracefully', async () => {
-    const badConfig = new MCPConfiguration({
+    const badConfig = new MCPClient({
       servers: {
         badServer: {
           command: 'nonexistent-command',
@@ -110,7 +110,7 @@ describe('MCPConfiguration', () => {
 
   describe('Instance Management', () => {
     it('should allow multiple instances with different IDs', async () => {
-      const config2 = new MCPConfiguration({
+      const config2 = new MCPClient({
         id: 'custom-id',
         servers: {
           stockPrice: {
@@ -130,7 +130,7 @@ describe('MCPConfiguration', () => {
     it('should allow reuse of configuration after closing', async () => {
       await mcp.disconnect();
 
-      const config2 = new MCPConfiguration({
+      const config2 = new MCPClient({
         servers: {
           stockPrice: {
             command: 'npx',
@@ -150,7 +150,7 @@ describe('MCPConfiguration', () => {
     });
 
     it('should throw error when creating duplicate instance without ID', async () => {
-      const existingConfig = new MCPConfiguration({
+      const existingConfig = new MCPClient({
         servers: {
           stockPrice: {
             command: 'npx',
@@ -164,7 +164,7 @@ describe('MCPConfiguration', () => {
 
       expect(
         () =>
-          new MCPConfiguration({
+          new MCPClient({
             servers: {
               stockPrice: {
                 command: 'npx',
@@ -175,14 +175,14 @@ describe('MCPConfiguration', () => {
               },
             },
           }),
-      ).toThrow(/MCPConfiguration was initialized multiple times/);
+      ).toThrow(/MCPClient was initialized multiple times/);
 
       await existingConfig.disconnect();
     });
   });
-  describe('MCPConfiguration Operation Timeouts', () => {
+  describe('MCPClient Operation Timeouts', () => {
     it('should respect custom timeout in configuration', async () => {
-      const config = new MCPConfiguration({
+      const config = new MCPClient({
         id: 'test-timeout-config',
         timeout: 3000, // 3 second timeout
         servers: {
@@ -208,7 +208,7 @@ describe('MCPConfiguration', () => {
     });
 
     it('should respect per-server timeout override', async () => {
-      const config = new MCPConfiguration({
+      const config = new MCPClient({
         id: 'test-server-timeout-config',
         timeout: 500, // Global timeout of 500ms
         servers: {
@@ -236,14 +236,15 @@ describe('MCPConfiguration', () => {
     });
   });
 
-  describe('MCPConfiguration Connection Timeout', () => {
+  describe('MCPClient Connection Timeout', () => {
     it('should throw timeout error for slow starting server', async () => {
-      const slowConfig = new MCPConfiguration({
+      const slowConfig = new MCPClient({
         id: 'test-slow-server',
         servers: {
           slowServer: {
             command: 'node',
             args: ['-e', 'setTimeout(() => process.exit(0), 65000)'], // Simulate a server that takes 65 seconds to start
+            timeout: 1000,
           },
         },
       });
@@ -252,14 +253,14 @@ describe('MCPConfiguration', () => {
       await slowConfig.disconnect();
     });
 
-    it('timeout should be longer than default timeout', async () => {
-      const slowConfig = new MCPConfiguration({
+    it('timeout should be longer than configured timeout', async () => {
+      const slowConfig = new MCPClient({
         id: 'test-slow-server',
-        timeout: 70000,
+        timeout: 2000,
         servers: {
           slowServer: {
             command: 'node',
-            args: ['-e', 'setTimeout(() => process.exit(0), 65000)'], // Simulate a server that takes 65 seconds to start
+            args: ['-e', 'setTimeout(() => process.exit(0), 1000)'], // Simulate a server that takes 1 second to start
           },
         },
       });
@@ -270,24 +271,8 @@ describe('MCPConfiguration', () => {
       await slowConfig.disconnect();
     });
 
-    it('should respect custom timeout configuration', async () => {
-      const quickConfig = new MCPConfiguration({
-        id: 'test-quick-timeout',
-        timeout: 1000, // Very short global timeout
-        servers: {
-          slowServer: {
-            command: 'node',
-            args: ['-e', 'setTimeout(() => process.exit(0), 30000)'], // Takes 30 seconds to exit
-          },
-        },
-      });
-
-      await expect(quickConfig.getTools()).rejects.toThrow(/Request timed out/);
-      await quickConfig.disconnect();
-    });
-
     it('should respect per-server timeout configuration', async () => {
-      const mixedConfig = new MCPConfiguration({
+      const mixedConfig = new MCPClient({
         id: 'test-mixed-timeout',
         timeout: 1000, // Short global timeout
         servers: {

package/src/configuration.ts

@@ -1,66 +1,100 @@
 import { MastraBase } from '@mastra/core/base';
 import { DEFAULT_REQUEST_TIMEOUT_MSEC } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import equal from 'fast-deep-equal';
 import { v5 as uuidv5 } from 'uuid';
-import { MastraMCPClient } from './client';
+import { InternalMastraMCPClient } from './client';
 import type { MastraMCPServerDefinition } from './client';
 
-const mastraMCPConfigurationInstances = new Map<string, InstanceType<typeof MCPConfiguration>>();
+const mcpClientInstances = new Map<string, InstanceType<typeof MCPClient>>();
 
-export interface MCPConfigurationOptions {
+export interface MCPClientOptions {
   id?: string;
   servers: Record<string, MastraMCPServerDefinition>;
   timeout?: number; // Optional global timeout
 }
 
-export class MCPConfiguration extends MastraBase {
+export class MCPClient extends MastraBase {
   private serverConfigs: Record<string, MastraMCPServerDefinition> = {};
   private id: string;
   private defaultTimeout: number;
+  private mcpClientsById = new Map<string, InternalMastraMCPClient>();
+  private disconnectPromise: Promise<void> | null = null;
 
-  constructor(args: MCPConfigurationOptions) {
-    super({ name: 'MCPConfiguration' });
+  constructor(args: MCPClientOptions) {
+    super({ name: 'MCPClient' });
     this.defaultTimeout = args.timeout ?? DEFAULT_REQUEST_TIMEOUT_MSEC;
     this.serverConfigs = args.servers;
     this.id = args.id ?? this.makeId();
 
+    if (args.id) {
+      this.id = args.id;
+      const cached = mcpClientInstances.get(this.id);
+
+      if (cached && !equal(cached.serverConfigs, args.servers)) {
+        const existingInstance = mcpClientInstances.get(this.id);
+        if (existingInstance) {
+          void existingInstance.disconnect();
+        }
+      }
+    } else {
+      this.id = this.makeId();
+    }
+
     // to prevent memory leaks return the same MCP server instance when configured the same way multiple times
-    const existingInstance = mastraMCPConfigurationInstances.get(this.id);
+    const existingInstance = mcpClientInstances.get(this.id);
     if (existingInstance) {
       if (!args.id) {
-        throw new Error(`MCPConfiguration was initialized multiple times with the same configuration options.
+        throw new Error(`MCPClient was initialized multiple times with the same configuration options.
 
 This error is intended to prevent memory leaks.
 
 To fix this you have three different options:
-1. If you need multiple MCPConfiguration class instances with identical server configurations, set an id when configuring: new MCPConfiguration({ id: "my-unique-id" })
-2. Call "await configuration.disconnect()" after you're done using the configuration and before you recreate another instance with the same options. If the identical MCPConfiguration instance is already closed at the time of re-creating it, you will not see this error.
-3. If you only need one instance of MCPConfiguration in your app, refactor your code so it's only created one time (ex. move it out of a loop into a higher scope code block)
+1. If you need multiple MCPClient class instances with identical server configurations, set an id when configuring: new MCPClient({ id: "my-unique-id" })
+2. Call "await client.disconnect()" after you're done using the client and before you recreate another instance with the same options. If the identical MCPClient instance is already closed at the time of re-creating it, you will not see this error.
+3. If you only need one instance of MCPClient in your app, refactor your code so it's only created one time (ex. move it out of a loop into a higher scope code block)
 `);
       }
       return existingInstance;
     }
+
+    mcpClientInstances.set(this.id, this);
     this.addToInstanceCache();
     return this;
   }
 
   private addToInstanceCache() {
-    if (!mastraMCPConfigurationInstances.has(this.id)) {
-      mastraMCPConfigurationInstances.set(this.id, this);
+    if (!mcpClientInstances.has(this.id)) {
+      mcpClientInstances.set(this.id, this);
     }
   }
 
   private makeId() {
     const text = JSON.stringify(this.serverConfigs).normalize('NFKC');
-    const idNamespace = uuidv5(`MCPConfiguration`, uuidv5.DNS);
+    const idNamespace = uuidv5(`MCPClient`, uuidv5.DNS);
 
     return uuidv5(text, idNamespace);
   }
 
   public async disconnect() {
-    mastraMCPConfigurationInstances.delete(this.id);
+    // Helps to prevent race condition
+    // If there is already a disconnect ongoing, return the existing promise.
+    if (this.disconnectPromise) {
+      return this.disconnectPromise;
+    }
+
+    this.disconnectPromise = (async () => {
+      try {
+        mcpClientInstances.delete(this.id);
 
-    await Promise.all(Array.from(this.mcpClientsById.values()).map(client => client.disconnect()));
-    this.mcpClientsById.clear();
+        // Disconnect all clients in the cache
+        await Promise.all(Array.from(this.mcpClientsById.values()).map(client => client.disconnect()));
+        this.mcpClientsById.clear();
+      } finally {
+        this.disconnectPromise = null;
+      }
+    })();
+
+    return this.disconnectPromise;
   }
 
   public async getTools() {
@@ -89,35 +123,61 @@ To fix this you have three different options:
     return connectedToolsets;
   }
 
-  private mcpClientsById = new Map<string, MastraMCPClient>();
+  /**
+   * Get the current session IDs for all connected MCP clients using the Streamable HTTP transport.
+   * Returns an object mapping server names to their session IDs.
+   */
+  get sessionIds(): Record<string, string> {
+    const sessionIds: Record<string, string> = {};
+    for (const [serverName, client] of this.mcpClientsById.entries()) {
+      if (client.sessionId) {
+        sessionIds[serverName] = client.sessionId;
+      }
+    }
+    return sessionIds;
+  }
+
   private async getConnectedClient(name: string, config: MastraMCPServerDefinition) {
+    // Helps to prevent race condition.
+    // If we want to call connect() we need to wait for the disconnect to complete first if any is ongoing.
+    if (this.disconnectPromise) {
+      await this.disconnectPromise;
+    }
+
     const exists = this.mcpClientsById.has(name);
+    const existingClient = this.mcpClientsById.get(name);
 
     if (exists) {
-      const mcpClient = this.mcpClientsById.get(name)!;
-      await mcpClient.connect();
-
-      return mcpClient;
+      // This is just to satisfy Typescript since technically you could have this.mcpClientsById.set('someKey', undefined);
+      // Should never reach this point basically we always create a new MastraMCPClient instance when we add to the Map.
+      if (!existingClient) {
+        throw new Error(`Client ${name} exists but is undefined`);
+      }
+      await existingClient.connect();
+      return existingClient;
     }
 
     this.logger.debug(`Connecting to ${name} MCP server`);
 
     // Create client with server configuration including log handler
-    const mcpClient = new MastraMCPClient({
+    const mcpClient = new InternalMastraMCPClient({
       name,
       server: config,
       timeout: config.timeout ?? this.defaultTimeout,
     });
 
     this.mcpClientsById.set(name, mcpClient);
+
     try {
       await mcpClient.connect();
     } catch (e) {
       this.mcpClientsById.delete(name);
-      this.logger.error(`MCPConfiguration errored connecting to MCP server ${name}`, {
+      this.logger.error(`MCPClient errored connecting to MCP server ${name}`, {
         error: e instanceof Error ? e.message : String(e),
       });
-      throw new Error(`Failed to connect to MCP server ${name}: ${e instanceof Error ? e.message : String(e)}`);
+      throw new Error(
+        `Failed to connect to MCP server ${name}: ${e instanceof Error ? e.stack || e.message : String(e)}`,
+      );
     }
 
     this.logger.debug(`Connected to ${name} MCP server`);
@@ -129,7 +189,7 @@ To fix this you have three different options:
     cb: (input: {
       serverName: string;
       tools: Record<string, any>; // <- any because we don't have proper tool schemas
-      client: InstanceType<typeof MastraMCPClient>;
+      client: InstanceType<typeof InternalMastraMCPClient>;
     }) => Promise<void>,
   ) {
     await Promise.all(
@@ -141,3 +201,24 @@ To fix this you have three different options:
     );
   }
 }
+
+/**
+ * @deprecated MCPConfigurationOptions is deprecated and will be removed in a future release. Use MCPClientOptions instead.
+ */
+export interface MCPConfigurationOptions {
+  id?: string;
+  servers: Record<string, MastraMCPServerDefinition>;
+  timeout?: number; // Optional global timeout
+}
+
+/**
+ * @deprecated MCPConfiguration is deprecated and will be removed in a future release. Use MCPClient instead.
+ */
+export class MCPConfiguration extends MCPClient {
+  constructor(args: MCPClientOptions) {
+    super(args);
+    this.logger.warn(
+      `MCPConfiguration has been renamed to MCPClient and MCPConfiguration is deprecated. The API is identical but the MCPConfiguration export will be removed in the future. Update your imports now to prevent future errors.`,
+    );
+  }
+}

package/src/index.ts

@@ -1,3 +1,4 @@
-export * from './client';
+export type { LoggingLevel, LogMessage, LogHandler, MastraMCPServerDefinition } from './client';
+export { MastraMCPClient } from './client';
 export * from './configuration';
 export * from './server';