@mastra/mcp 0.2.7-alpha.8 → 0.3.0-alpha.10

package/.turbo/turbo-build.log

@@ -1,23 +1,23 @@
 
-> @mastra/mcp@0.2.7-alpha.8 build /home/runner/work/mastra/mastra/packages/mcp
+> @mastra/mcp@0.3.0-alpha.10 build /home/runner/work/mastra/mastra/packages/mcp
 > tsup src/index.ts --format esm,cjs --experimental-dts --clean --treeshake
 
 CLI Building entry: src/index.ts
 CLI Using tsconfig: tsconfig.json
 CLI tsup v8.3.6
 TSC Build start
-TSC ⚡️ Build success in 9772ms
+TSC ⚡️ Build success in 11301ms
 DTS Build start
 CLI Target: es2022
 Analysis will use the bundled TypeScript version 5.7.3
 Writing package typings: /home/runner/work/mastra/mastra/packages/mcp/dist/_tsup-dts-rollup.d.ts
 Analysis will use the bundled TypeScript version 5.7.3
 Writing package typings: /home/runner/work/mastra/mastra/packages/mcp/dist/_tsup-dts-rollup.d.cts
-DTS ⚡️ Build success in 9475ms
+DTS ⚡️ Build success in 11798ms
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-CJS dist/index.cjs 2.22 KB
-CJS ⚡️ Build success in 344ms
-ESM dist/index.js 2.19 KB
-ESM ⚡️ Build success in 348ms
+ESM dist/index.js 6.82 KB
+ESM ⚡️ Build success in 800ms
+CJS dist/index.cjs 6.87 KB
+CJS ⚡️ Build success in 798ms

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @mastra/mcp
 
+## 0.3.0-alpha.10
+
+### Minor Changes
+
+- dd7a09a: Added new MCPConfiguration class for managing multiple MCP server tools/toolsets. Fixed a bug where MCPClient env would overwrite PATH env var. Fixed a bug where MCP servers would be killed non-gracefully leading to printing huge errors on every code save when running mastra dev
+
+### Patch Changes
+
+- Updated dependencies [a910463]
+  - @mastra/core@0.5.0-alpha.10
+
+## 0.2.7-alpha.9
+
+### Patch Changes
+
+- Updated dependencies [e9fbac5]
+- Updated dependencies [1e8bcbc]
+- Updated dependencies [aeb5e36]
+- Updated dependencies [f2301de]
+  - @mastra/core@0.5.0-alpha.9
+
 ## 0.2.7-alpha.8
 
 ### Patch Changes

package/README.md

@@ -53,6 +53,114 @@ const tools = await client.tools();
 await client.disconnect();
 ```
 
+## Managing Multiple MCP Servers
+
+For applications that need to interact with multiple MCP servers, the `MCPConfiguration` class provides a convenient way to manage multiple server connections and their tools:
+
+```typescript
+import { MCPConfiguration } from '@mastra/mcp';
+
+const mcp = new MCPConfiguration({
+  servers: {
+    // Stdio-based server
+    stockPrice: {
+      command: 'npx',
+      args: ['tsx', 'stock-price.ts'],
+      env: {
+        API_KEY: 'your-api-key',
+      },
+    },
+    // SSE-based server
+    weather: {
+      url: new URL('http://localhost:8080/sse'),
+    },
+  },
+});
+
+// Get all tools from all configured servers namespaced with the server name
+const tools = await mcp.getTools();
+
+// Get tools grouped into a toolset object per-server
+const toolsets = await mcp.getToolsets();
+```
+
+### Tools vs Toolsets
+
+The MCPConfiguration class provides two ways to access MCP tools:
+
+#### Tools (`getTools()`)
+
+Use this when:
+
+- You have a single MCP connection
+- The tools are used by a single user/context (CLI tools, automation scripts, etc)
+- Tool configuration (API keys, credentials) remains constant
+- You want to initialize an Agent with a fixed set of tools
+
+```typescript
+const agent = new Agent({
+  name: 'CLI Assistant',
+  instructions: 'You help users with CLI tasks',
+  model: openai('gpt-4'),
+  tools: await mcp.getTools(), // Tools are fixed at agent creation
+});
+```
+
+#### Toolsets (`getToolsets()`)
+
+Use this when:
+
+- You need per-request tool configuration
+- Tools need different credentials per user
+- Running in a multi-user environment (web app, API, etc)
+- Tool configuration needs to change dynamically
+
+```typescript
+import { MCPConfiguration } from '@mastra/mcp';
+import { Agent } from '@mastra/core/agent';
+import { openai } from '@ai-sdk/openai';
+
+// Configure MCP servers with user-specific settings before getting toolsets
+const mcp = new MCPConfiguration({
+  servers: {
+    stockPrice: {
+      command: 'npx',
+      args: ['tsx', 'weather-mcp.ts'],
+      env: {
+        // These would be different per user
+        API_KEY: 'user-1-api-key',
+      },
+    },
+    weather: {
+      url: new URL('http://localhost:8080/sse'),
+      requestInit: {
+        headers: {
+          // These would be different per user
+          Authorization: 'Bearer user-1-token',
+        },
+      },
+    },
+  },
+});
+
+// Get the current toolsets configured for this user
+const toolsets = await mcp.getToolsets();
+
+// Use the agent with user-specific tool configurations
+const response = await agent.generate('What is the weather in London?', {
+  toolsets,
+});
+
+console.log(response.text);
+```
+
+The `MCPConfiguration` class automatically:
+
+- Manages connections to multiple MCP servers
+- Namespaces tools to prevent naming conflicts
+- Handles connection lifecycle and cleanup
+- Provides both flat and grouped access to tools
+
 ## Configuration
 
 ### Required Parameters

package/dist/_tsup-dts-rollup.d.cts

@@ -1,18 +1,21 @@
 import type { ClientCapabilities } from '@modelcontextprotocol/sdk/types.js';
+import { FastMCP } from 'fastmcp';
+import { MastraBase } from '@mastra/core/base';
 import type { Protocol } from '@modelcontextprotocol/sdk/shared/protocol.js';
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 import type { StdioServerParameters } from '@modelcontextprotocol/sdk/client/stdio.js';
 
-declare class MastraMCPClient {
+declare class MastraMCPClient extends MastraBase {
     name: string;
     private transport;
     private client;
     constructor({ name, version, server, capabilities, }: {
         name: string;
-        server: StdioServerParameters | SSEClientParameters;
+        server: MastraMCPServerDefinition;
         capabilities?: ClientCapabilities;
         version?: string;
     });
+    private isConnected;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     resources(): Promise<ReturnType<Protocol<any, any, any>['request']>>;
@@ -21,6 +24,33 @@ declare class MastraMCPClient {
 export { MastraMCPClient }
 export { MastraMCPClient as MastraMCPClient_alias_1 }
 
+declare type MastraMCPServerDefinition = StdioServerParameters | SSEClientParameters;
+export { MastraMCPServerDefinition }
+export { MastraMCPServerDefinition as MastraMCPServerDefinition_alias_1 }
+
+declare class MCPConfiguration extends MastraBase {
+    private serverConfigs;
+    private id;
+    constructor(args: {
+        id?: string;
+        servers: Record<string, MastraMCPServerDefinition>;
+    });
+    private addToInstanceCache;
+    private makeId;
+    disconnect(): Promise<void>;
+    getTools(): Promise<Record<string, any>>;
+    getToolsets(): Promise<Record<string, Record<string, any>>>;
+    private mcpClientsById;
+    private getConnectedClient;
+    private eachClientTools;
+}
+export { MCPConfiguration }
+export { MCPConfiguration as MCPConfiguration_alias_1 }
+
+export declare const server: FastMCP<undefined>;
+
+export declare const server_alias_1: FastMCP<undefined>;
+
 declare type SSEClientParameters = {
     url: URL;
 } & ConstructorParameters<typeof SSEClientTransport>[1];

package/dist/_tsup-dts-rollup.d.ts

@@ -1,18 +1,21 @@
 import type { ClientCapabilities } from '@modelcontextprotocol/sdk/types.js';
+import { FastMCP } from 'fastmcp';
+import { MastraBase } from '@mastra/core/base';
 import type { Protocol } from '@modelcontextprotocol/sdk/shared/protocol.js';
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 import type { StdioServerParameters } from '@modelcontextprotocol/sdk/client/stdio.js';
 
-declare class MastraMCPClient {
+declare class MastraMCPClient extends MastraBase {
     name: string;
     private transport;
     private client;
     constructor({ name, version, server, capabilities, }: {
         name: string;
-        server: StdioServerParameters | SSEClientParameters;
+        server: MastraMCPServerDefinition;
         capabilities?: ClientCapabilities;
         version?: string;
     });
+    private isConnected;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     resources(): Promise<ReturnType<Protocol<any, any, any>['request']>>;
@@ -21,6 +24,33 @@ declare class MastraMCPClient {
 export { MastraMCPClient }
 export { MastraMCPClient as MastraMCPClient_alias_1 }
 
+declare type MastraMCPServerDefinition = StdioServerParameters | SSEClientParameters;
+export { MastraMCPServerDefinition }
+export { MastraMCPServerDefinition as MastraMCPServerDefinition_alias_1 }
+
+declare class MCPConfiguration extends MastraBase {
+    private serverConfigs;
+    private id;
+    constructor(args: {
+        id?: string;
+        servers: Record<string, MastraMCPServerDefinition>;
+    });
+    private addToInstanceCache;
+    private makeId;
+    disconnect(): Promise<void>;
+    getTools(): Promise<Record<string, any>>;
+    getToolsets(): Promise<Record<string, Record<string, any>>>;
+    private mcpClientsById;
+    private getConnectedClient;
+    private eachClientTools;
+}
+export { MCPConfiguration }
+export { MCPConfiguration as MCPConfiguration_alias_1 }
+
+export declare const server: FastMCP<undefined>;
+
+export declare const server_alias_1: FastMCP<undefined>;
+
 declare type SSEClientParameters = {
     url: URL;
 } & ConstructorParameters<typeof SSEClientTransport>[1];

package/dist/index.cjs

@@ -1,14 +1,17 @@
 'use strict';
 
+var base = require('@mastra/core/base');
 var tools = require('@mastra/core/tools');
 var utils = require('@mastra/core/utils');
 var index_js = require('@modelcontextprotocol/sdk/client/index.js');
 var sse_js = require('@modelcontextprotocol/sdk/client/sse.js');
 var stdio_js = require('@modelcontextprotocol/sdk/client/stdio.js');
 var types_js = require('@modelcontextprotocol/sdk/types.js');
+var exitHook = require('exit-hook');
+var uuid = require('uuid');
 
 // src/client.ts
-var MastraMCPClient = class {
+var MastraMCPClient = class extends base.MastraBase {
   name;
   transport;
   client;
@@ -18,6 +21,7 @@ var MastraMCPClient = class {
     server,
     capabilities = {}
   }) {
+    super({ name: "MastraMCPClient" });
     this.name = name;
     if (`url` in server) {
       this.transport = new sse_js.SSEClientTransport(server.url, {
@@ -25,7 +29,11 @@ var MastraMCPClient = class {
         eventSourceInit: server.eventSourceInit
       });
     } else {
-      this.transport = new stdio_js.StdioClientTransport(server);
+      this.transport = new stdio_js.StdioClientTransport({
+        ...server,
+        // without ...getDefaultEnvironment() commands like npx will fail because there will be no PATH env var
+        env: { ...stdio_js.getDefaultEnvironment(), ...server.env || {} }
+      });
     }
     this.client = new index_js.Client(
       {
@@ -37,8 +45,32 @@ var MastraMCPClient = class {
       }
     );
   }
+  isConnected = false;
   async connect() {
-    return await this.client.connect(this.transport);
+    if (this.isConnected) return;
+    try {
+      await this.client.connect(this.transport);
+      this.isConnected = true;
+      this.client.onclose = () => {
+        this.isConnected = false;
+      };
+      await this.client.setLoggingLevel(`critical`);
+      exitHook.asyncExitHook(
+        async () => {
+          this.logger.debug(`Disconnecting ${this.name} MCP server`);
+          await this.disconnect();
+        },
+        { wait: 5e3 }
+      );
+      process.on("SIGTERM", () => exitHook.gracefulExit());
+    } catch (e) {
+      this.logger.error(
+        `Failed connecting to MCPClient with name ${this.name}.
+${e instanceof Error ? e.stack : JSON.stringify(e, null, 2)}`
+      );
+      this.isConnected = false;
+      throw e;
+    }
   }
   async disconnect() {
     return await this.client.close();
@@ -77,5 +109,107 @@ var MastraMCPClient = class {
     return toolsRes;
   }
 };
+var mastraMCPConfigurationInstances = /* @__PURE__ */ new Map();
+var MCPConfiguration = class extends base.MastraBase {
+  serverConfigs = {};
+  id;
+  constructor(args) {
+    super({ name: "MCPConfiguration" });
+    this.serverConfigs = args.servers;
+    this.id = args.id ?? this.makeId();
+    const existingInstance = mastraMCPConfigurationInstances.get(this.id);
+    if (existingInstance) {
+      if (!args.id) {
+        throw new Error(`MCPConfiguration 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)
+`);
+      }
+      return existingInstance;
+    }
+    this.addToInstanceCache();
+    return this;
+  }
+  addToInstanceCache() {
+    if (!mastraMCPConfigurationInstances.has(this.id)) {
+      mastraMCPConfigurationInstances.set(this.id, this);
+    }
+  }
+  makeId() {
+    const text = JSON.stringify(this.serverConfigs).normalize("NFKC");
+    const idNamespace = uuid.v5(`MCPConfiguration`, uuid.v5.DNS);
+    return uuid.v5(text, idNamespace);
+  }
+  async disconnect() {
+    mastraMCPConfigurationInstances.delete(this.id);
+    for (const serverName of Object.keys(this.serverConfigs)) {
+      const client = this.mcpClientsById.get(serverName);
+      if (client) {
+        await client.disconnect();
+      }
+    }
+  }
+  async getTools() {
+    this.addToInstanceCache();
+    const connectedTools = {};
+    await this.eachClientTools(async ({ serverName, tools }) => {
+      for (const [toolName, toolConfig] of Object.entries(tools)) {
+        connectedTools[`${serverName}_${toolName}`] = toolConfig;
+      }
+    });
+    return connectedTools;
+  }
+  async getToolsets() {
+    this.addToInstanceCache();
+    const connectedToolsets = {};
+    await this.eachClientTools(async ({ serverName, tools }) => {
+      if (tools) {
+        connectedToolsets[serverName] = tools;
+      }
+    });
+    return connectedToolsets;
+  }
+  mcpClientsById = /* @__PURE__ */ new Map();
+  async getConnectedClient(name, config) {
+    const exists = this.mcpClientsById.has(name);
+    if (exists) {
+      const mcpClient2 = this.mcpClientsById.get(name);
+      await mcpClient2.connect();
+      return mcpClient2;
+    }
+    this.logger.debug(`Connecting to ${name} MCP server`);
+    const mcpClient = new MastraMCPClient({
+      name,
+      server: config
+    });
+    this.mcpClientsById.set(name, mcpClient);
+    try {
+      await mcpClient.connect();
+    } catch (e) {
+      this.mcpClientsById.delete(name);
+      this.logger.error(`MCPConfiguraiton errored connecting to MCP server ${name}`);
+      throw e;
+    }
+    this.logger.debug(`Connected to ${name} MCP server`);
+    return mcpClient;
+  }
+  async eachClientTools(cb) {
+    for (const [serverName, serverConfig] of Object.entries(this.serverConfigs)) {
+      const client = await this.getConnectedClient(serverName, serverConfig);
+      const tools = await client.tools();
+      await cb({
+        serverName,
+        tools,
+        client
+      });
+    }
+  }
+};
 
+exports.MCPConfiguration = MCPConfiguration;
 exports.MastraMCPClient = MastraMCPClient;

package/dist/index.d.cts

@@ -1 +1,3 @@
+export { MastraMCPServerDefinition_alias_1 as MastraMCPServerDefinition } from './_tsup-dts-rollup.cjs';
 export { MastraMCPClient_alias_1 as MastraMCPClient } from './_tsup-dts-rollup.cjs';
+export { MCPConfiguration_alias_1 as MCPConfiguration } from './_tsup-dts-rollup.cjs';

package/dist/index.d.ts

@@ -1 +1,3 @@
+export { MastraMCPServerDefinition_alias_1 as MastraMCPServerDefinition } from './_tsup-dts-rollup.js';
 export { MastraMCPClient_alias_1 as MastraMCPClient } from './_tsup-dts-rollup.js';
+export { MCPConfiguration_alias_1 as MCPConfiguration } from './_tsup-dts-rollup.js';

package/dist/index.js

@@ -1,12 +1,15 @@
+import { MastraBase } from '@mastra/core/base';
 import { createTool } from '@mastra/core/tools';
 import { jsonSchemaToModel } from '@mastra/core/utils';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
-import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StdioClientTransport, getDefaultEnvironment } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { ListResourcesResultSchema } from '@modelcontextprotocol/sdk/types.js';
+import { asyncExitHook, gracefulExit } from 'exit-hook';
+import { v5 } from 'uuid';
 
 // src/client.ts
-var MastraMCPClient = class {
+var MastraMCPClient = class extends MastraBase {
   name;
   transport;
   client;
@@ -16,6 +19,7 @@ var MastraMCPClient = class {
     server,
     capabilities = {}
   }) {
+    super({ name: "MastraMCPClient" });
     this.name = name;
     if (`url` in server) {
       this.transport = new SSEClientTransport(server.url, {
@@ -23,7 +27,11 @@ var MastraMCPClient = class {
         eventSourceInit: server.eventSourceInit
       });
     } else {
-      this.transport = new StdioClientTransport(server);
+      this.transport = new StdioClientTransport({
+        ...server,
+        // without ...getDefaultEnvironment() commands like npx will fail because there will be no PATH env var
+        env: { ...getDefaultEnvironment(), ...server.env || {} }
+      });
     }
     this.client = new Client(
       {
@@ -35,8 +43,32 @@ var MastraMCPClient = class {
       }
     );
   }
+  isConnected = false;
   async connect() {
-    return await this.client.connect(this.transport);
+    if (this.isConnected) return;
+    try {
+      await this.client.connect(this.transport);
+      this.isConnected = true;
+      this.client.onclose = () => {
+        this.isConnected = false;
+      };
+      await this.client.setLoggingLevel(`critical`);
+      asyncExitHook(
+        async () => {
+          this.logger.debug(`Disconnecting ${this.name} MCP server`);
+          await this.disconnect();
+        },
+        { wait: 5e3 }
+      );
+      process.on("SIGTERM", () => gracefulExit());
+    } catch (e) {
+      this.logger.error(
+        `Failed connecting to MCPClient with name ${this.name}.
+${e instanceof Error ? e.stack : JSON.stringify(e, null, 2)}`
+      );
+      this.isConnected = false;
+      throw e;
+    }
   }
   async disconnect() {
     return await this.client.close();
@@ -75,5 +107,106 @@ var MastraMCPClient = class {
     return toolsRes;
   }
 };
+var mastraMCPConfigurationInstances = /* @__PURE__ */ new Map();
+var MCPConfiguration = class extends MastraBase {
+  serverConfigs = {};
+  id;
+  constructor(args) {
+    super({ name: "MCPConfiguration" });
+    this.serverConfigs = args.servers;
+    this.id = args.id ?? this.makeId();
+    const existingInstance = mastraMCPConfigurationInstances.get(this.id);
+    if (existingInstance) {
+      if (!args.id) {
+        throw new Error(`MCPConfiguration 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)
+`);
+      }
+      return existingInstance;
+    }
+    this.addToInstanceCache();
+    return this;
+  }
+  addToInstanceCache() {
+    if (!mastraMCPConfigurationInstances.has(this.id)) {
+      mastraMCPConfigurationInstances.set(this.id, this);
+    }
+  }
+  makeId() {
+    const text = JSON.stringify(this.serverConfigs).normalize("NFKC");
+    const idNamespace = v5(`MCPConfiguration`, v5.DNS);
+    return v5(text, idNamespace);
+  }
+  async disconnect() {
+    mastraMCPConfigurationInstances.delete(this.id);
+    for (const serverName of Object.keys(this.serverConfigs)) {
+      const client = this.mcpClientsById.get(serverName);
+      if (client) {
+        await client.disconnect();
+      }
+    }
+  }
+  async getTools() {
+    this.addToInstanceCache();
+    const connectedTools = {};
+    await this.eachClientTools(async ({ serverName, tools }) => {
+      for (const [toolName, toolConfig] of Object.entries(tools)) {
+        connectedTools[`${serverName}_${toolName}`] = toolConfig;
+      }
+    });
+    return connectedTools;
+  }
+  async getToolsets() {
+    this.addToInstanceCache();
+    const connectedToolsets = {};
+    await this.eachClientTools(async ({ serverName, tools }) => {
+      if (tools) {
+        connectedToolsets[serverName] = tools;
+      }
+    });
+    return connectedToolsets;
+  }
+  mcpClientsById = /* @__PURE__ */ new Map();
+  async getConnectedClient(name, config) {
+    const exists = this.mcpClientsById.has(name);
+    if (exists) {
+      const mcpClient2 = this.mcpClientsById.get(name);
+      await mcpClient2.connect();
+      return mcpClient2;
+    }
+    this.logger.debug(`Connecting to ${name} MCP server`);
+    const mcpClient = new MastraMCPClient({
+      name,
+      server: config
+    });
+    this.mcpClientsById.set(name, mcpClient);
+    try {
+      await mcpClient.connect();
+    } catch (e) {
+      this.mcpClientsById.delete(name);
+      this.logger.error(`MCPConfiguraiton errored connecting to MCP server ${name}`);
+      throw e;
+    }
+    this.logger.debug(`Connected to ${name} MCP server`);
+    return mcpClient;
+  }
+  async eachClientTools(cb) {
+    for (const [serverName, serverConfig] of Object.entries(this.serverConfigs)) {
+      const client = await this.getConnectedClient(serverName, serverConfig);
+      const tools = await client.tools();
+      await cb({
+        serverName,
+        tools,
+        client
+      });
+    }
+  }
+};
 
-export { MastraMCPClient };
+export { MCPConfiguration, MastraMCPClient };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp",
-  "version": "0.2.7-alpha.8",
+  "version": "0.3.0-alpha.10",
   "description": "",
   "type": "module",
   "main": "dist/index.js",
@@ -24,17 +24,20 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.1.1",
     "date-fns": "^4.1.0",
-    "zod": "^3.24.1",
-    "@mastra/core": "^0.5.0-alpha.8"
+    "exit-hook": "^4.0.0",
+    "uuid": "^11.1.0",
+    "@mastra/core": "^0.5.0-alpha.10"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^1.1.6",
     "@microsoft/api-extractor": "^7.49.2",
     "@types/node": "^22.13.1",
+    "eslint": "^9.20.1",
+    "fastmcp": "^1.20.2",
     "tsup": "^8.0.1",
     "typescript": "^5.7.3",
     "vitest": "^3.0.4",
-    "eslint": "^9.20.1",
+    "zod": "^3.24.2",
     "@internal/lint": "0.0.0"
   },
   "scripts": {

package/src/__fixtures__/stock-price.ts

@@ -0,0 +1,44 @@
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+
+const getStockPrice = async (symbol: string) => {
+  // Return mock data for testing
+  return {
+    symbol,
+    currentPrice: '150.00',
+  };
+};
+
+const server = new FastMCP({
+  name: 'Stock Price Server',
+  version: '1.0.0',
+});
+
+const stockSchema = z.object({
+  symbol: z.string(),
+});
+
+server.addTool({
+  name: 'getStockPrice',
+  description: "Fetches the last day's closing stock price for a given symbol",
+  parameters: stockSchema,
+  execute: async (args: z.infer<typeof stockSchema>) => {
+    try {
+      const priceData = await getStockPrice(args.symbol);
+      return JSON.stringify(priceData);
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new Error(`Stock price fetch failed: ${error.message}`);
+      }
+      throw error;
+    }
+  },
+});
+
+// Start the server with stdio transport
+void server.start({
+  transportType: 'stdio',
+});
+
+export { server };
+

package/src/__fixtures__/weather.ts

@@ -0,0 +1,52 @@
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+
+const getWeather = async (location: string) => {
+  // Return mock data for testing
+  return {
+    temperature: 20,
+    feelsLike: 18,
+    humidity: 65,
+    windSpeed: 10,
+    windGust: 15,
+    conditions: 'Clear sky',
+    location,
+  };
+};
+
+const server = new FastMCP({
+  name: 'Weather Server',
+  version: '1.0.0',
+});
+
+const weatherSchema = z.object({
+  location: z.string().describe('City name'),
+});
+
+server.addTool({
+  name: 'getWeather',
+  description: 'Get current weather for a location',
+  parameters: weatherSchema,
+  execute: async (args: z.infer<typeof weatherSchema>) => {
+    try {
+      const weatherData = await getWeather(args.location);
+      return JSON.stringify(weatherData);
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new Error(`Weather fetch failed: ${error.message}`);
+      }
+      throw error;
+    }
+  },
+});
+
+// Start the server with SSE support
+void server.start({
+  transportType: 'sse',
+  sse: {
+    endpoint: '/sse',
+    port: 60808,
+  },
+});
+
+export { server };

package/src/client.ts

@@ -1,19 +1,24 @@
+import { MastraBase } from '@mastra/core/base';
 import { createTool } from '@mastra/core/tools';
 import { jsonSchemaToModel } from '@mastra/core/utils';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
-import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { getDefaultEnvironment, StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import type { StdioServerParameters } from '@modelcontextprotocol/sdk/client/stdio.js';
 import type { Protocol } from '@modelcontextprotocol/sdk/shared/protocol.js';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import type { ClientCapabilities } from '@modelcontextprotocol/sdk/types.js';
 import { ListResourcesResultSchema } from '@modelcontextprotocol/sdk/types.js';
 
+import { asyncExitHook, gracefulExit } from 'exit-hook';
+
 type SSEClientParameters = {
   url: URL;
 } & ConstructorParameters<typeof SSEClientTransport>[1];
 
-export class MastraMCPClient {
+export type MastraMCPServerDefinition = StdioServerParameters | SSEClientParameters;
+
+export class MastraMCPClient extends MastraBase {
   name: string;
   private transport: Transport;
   private client: Client;
@@ -24,10 +29,11 @@ export class MastraMCPClient {
     capabilities = {},
   }: {
     name: string;
-    server: StdioServerParameters | SSEClientParameters;
+    server: MastraMCPServerDefinition;
     capabilities?: ClientCapabilities;
     version?: string;
   }) {
+    super({ name: 'MastraMCPClient' });
     this.name = name;
 
     if (`url` in server) {
@@ -36,7 +42,11 @@ export class MastraMCPClient {
         eventSourceInit: server.eventSourceInit,
       });
     } else {
-      this.transport = new StdioClientTransport(server);
+      this.transport = new StdioClientTransport({
+        ...server,
+        // without ...getDefaultEnvironment() commands like npx will fail because there will be no PATH env var
+        env: { ...getDefaultEnvironment(), ...(server.env || {}) },
+      });
     }
 
     this.client = new Client(
@@ -50,8 +60,33 @@ export class MastraMCPClient {
     );
   }
 
+  private isConnected = false;
+
   async connect() {
-    return await this.client.connect(this.transport);
+    if (this.isConnected) return;
+    try {
+      await this.client.connect(this.transport);
+      this.isConnected = true;
+      this.client.onclose = () => {
+        this.isConnected = false;
+      };
+      await this.client.setLoggingLevel(`critical`);
+      asyncExitHook(
+        async () => {
+          this.logger.debug(`Disconnecting ${this.name} MCP server`);
+          await this.disconnect();
+        },
+        { wait: 5000 },
+      );
+
+      process.on('SIGTERM', () => gracefulExit());
+    } catch (e) {
+      this.logger.error(
+        `Failed connecting to MCPClient with name ${this.name}.\n${e instanceof Error ? e.stack : JSON.stringify(e, null, 2)}`,
+      );
+      this.isConnected = false;
+      throw e;
+    }
   }
 
   async disconnect() {

package/src/configuration.test.ts

@@ -0,0 +1,181 @@
+import { spawn } from 'child_process';
+import path from 'path';
+import { describe, it, expect, beforeEach, afterEach, afterAll, beforeAll } from 'vitest';
+import { MCPConfiguration } from './configuration';
+
+describe('MCPConfiguration', () => {
+  let mcp: MCPConfiguration;
+  let weatherProcess: ReturnType<typeof spawn>;
+
+  beforeAll(async () => {
+    // Start the weather SSE server
+    weatherProcess = spawn('npx', ['-y', 'tsx', path.join(__dirname, '__fixtures__/weather.ts')]);
+
+    // Wait for SSE server to be ready
+    let resolved = false;
+    await new Promise<void>((resolve, reject) => {
+      weatherProcess.on(`exit`, () => {
+        if (!resolved) reject();
+      });
+      if (weatherProcess.stderr) {
+        weatherProcess.stderr.on(`data`, chunk => {
+          console.error(chunk.toString());
+        });
+      }
+      if (weatherProcess.stdout) {
+        weatherProcess.stdout.on('data', chunk => {
+          if (chunk.toString().includes('server is running on SSE')) {
+            resolve();
+            resolved = true;
+          }
+        });
+      }
+    });
+  });
+
+  beforeEach(async () => {
+    mcp = new MCPConfiguration({
+      servers: {
+        stockPrice: {
+          command: 'npx',
+          args: ['-y', 'tsx', path.join(__dirname, '__fixtures__/stock-price.ts')],
+          env: {
+            FAKE_CREDS: 'test',
+          },
+        },
+        weather: {
+          url: new URL('http://localhost:60808/sse'),
+        },
+      },
+    });
+  });
+
+  afterEach(async () => {
+    // Clean up any connected clients
+    await mcp.disconnect();
+  });
+
+  afterAll(async () => {
+    // Kill the weather SSE server
+    weatherProcess.kill('SIGINT');
+  });
+
+  it('should initialize with server configurations', () => {
+    expect(mcp['serverConfigs']).toEqual({
+      stockPrice: {
+        command: 'npx',
+        args: ['-y', 'tsx', path.join(__dirname, '__fixtures__/stock-price.ts')],
+        env: {
+          FAKE_CREDS: 'test',
+        },
+      },
+      weather: {
+        url: new URL('http://localhost:60808/sse'),
+      },
+    });
+  });
+
+  it('should get connected tools with namespaced tool names', async () => {
+    const connectedTools = await mcp.getTools();
+
+    // Each tool should be namespaced with its server name
+    expect(connectedTools).toHaveProperty('stockPrice_getStockPrice');
+    expect(connectedTools).toHaveProperty('weather_getWeather');
+  });
+
+  it('should get connected toolsets grouped by server', async () => {
+    const connectedToolsets = await mcp.getToolsets();
+
+    expect(connectedToolsets).toHaveProperty('stockPrice');
+    expect(connectedToolsets).toHaveProperty('weather');
+    expect(connectedToolsets.stockPrice).toHaveProperty('getStockPrice');
+    expect(connectedToolsets.weather).toHaveProperty('getWeather');
+  });
+
+  it('should handle connection errors gracefully', async () => {
+    const badConfig = new MCPConfiguration({
+      servers: {
+        badServer: {
+          command: 'nonexistent-command',
+          args: [],
+        },
+      },
+    });
+
+    await expect(badConfig.getTools()).rejects.toThrow();
+    await badConfig.disconnect();
+  });
+
+  describe('Instance Management', () => {
+    it('should allow multiple instances with different IDs', async () => {
+      const config2 = new MCPConfiguration({
+        id: 'custom-id',
+        servers: {
+          stockPrice: {
+            command: 'npx',
+            args: ['-y', 'tsx', path.join(__dirname, '__fixtures__/stock-price.ts')],
+            env: {
+              FAKE_CREDS: 'test',
+            },
+          },
+        },
+      });
+
+      expect(config2).not.toBe(mcp);
+      await config2.disconnect();
+    });
+
+    it('should allow reuse of configuration after closing', async () => {
+      await mcp.disconnect();
+
+      const config2 = new MCPConfiguration({
+        servers: {
+          stockPrice: {
+            command: 'npx',
+            args: ['-y', 'tsx', path.join(__dirname, '__fixtures__/stock-price.ts')],
+            env: {
+              FAKE_CREDS: 'test',
+            },
+          },
+          weather: {
+            url: new URL('http://localhost:60808/sse'),
+          },
+        },
+      });
+
+      expect(config2).not.toBe(mcp);
+      await config2.disconnect();
+    });
+
+    it('should throw error when creating duplicate instance without ID', async () => {
+      const existingConfig = new MCPConfiguration({
+        servers: {
+          stockPrice: {
+            command: 'npx',
+            args: ['-y', 'tsx', path.join(__dirname, '__fixtures__/stock-price.ts')],
+            env: {
+              FAKE_CREDS: 'test',
+            },
+          },
+        },
+      });
+
+      expect(
+        () =>
+          new MCPConfiguration({
+            servers: {
+              stockPrice: {
+                command: 'npx',
+                args: ['-y', 'tsx', path.join(__dirname, '__fixtures__/stock-price.ts')],
+                env: {
+                  FAKE_CREDS: 'test',
+                },
+              },
+            },
+          }),
+      ).toThrow(/MCPConfiguration was initialized multiple times/);
+
+      await existingConfig.disconnect();
+    });
+  });
+});

package/src/configuration.ts

@@ -0,0 +1,136 @@
+import { MastraBase } from '@mastra/core/base';
+import { v5 as uuidv5 } from 'uuid';
+import { MastraMCPClient } from './client';
+import type { MastraMCPServerDefinition } from './client';
+
+const mastraMCPConfigurationInstances = new Map<string, InstanceType<typeof MCPConfiguration>>();
+
+export class MCPConfiguration extends MastraBase {
+  private serverConfigs: Record<string, MastraMCPServerDefinition> = {};
+  private id: string;
+
+  constructor(args: { id?: string; servers: Record<string, MastraMCPServerDefinition> }) {
+    super({ name: 'MCPConfiguration' });
+    this.serverConfigs = args.servers;
+    this.id = args.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);
+    if (existingInstance) {
+      if (!args.id) {
+        throw new Error(`MCPConfiguration 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)
+`);
+      }
+      return existingInstance;
+    }
+    this.addToInstanceCache();
+    return this;
+  }
+
+  private addToInstanceCache() {
+    if (!mastraMCPConfigurationInstances.has(this.id)) {
+      mastraMCPConfigurationInstances.set(this.id, this);
+    }
+  }
+
+  private makeId() {
+    const text = JSON.stringify(this.serverConfigs).normalize('NFKC');
+    const idNamespace = uuidv5(`MCPConfiguration`, uuidv5.DNS);
+
+    return uuidv5(text, idNamespace);
+  }
+
+  public async disconnect() {
+    mastraMCPConfigurationInstances.delete(this.id);
+
+    for (const serverName of Object.keys(this.serverConfigs)) {
+      const client = this.mcpClientsById.get(serverName);
+      if (client) {
+        await client.disconnect();
+      }
+    }
+  }
+
+  public async getTools() {
+    this.addToInstanceCache();
+    const connectedTools: Record<string, any> = {}; // <- any because we don't have proper tool schemas
+
+    await this.eachClientTools(async ({ serverName, tools }) => {
+      for (const [toolName, toolConfig] of Object.entries(tools)) {
+        connectedTools[`${serverName}_${toolName}`] = toolConfig; // namespace tool to prevent tool name conflicts between servers
+      }
+    });
+
+    return connectedTools;
+  }
+
+  public async getToolsets() {
+    this.addToInstanceCache();
+    const connectedToolsets: Record<string, Record<string, any>> = {}; // <- any because we don't have proper tool schemas
+
+    await this.eachClientTools(async ({ serverName, tools }) => {
+      if (tools) {
+        connectedToolsets[serverName] = tools;
+      }
+    });
+
+    return connectedToolsets;
+  }
+
+  private mcpClientsById = new Map<string, MastraMCPClient>();
+  private async getConnectedClient(name: string, config: MastraMCPServerDefinition) {
+    const exists = this.mcpClientsById.has(name);
+
+    if (exists) {
+      const mcpClient = this.mcpClientsById.get(name)!;
+      await mcpClient.connect();
+
+      return mcpClient;
+    }
+
+    this.logger.debug(`Connecting to ${name} MCP server`);
+
+    const mcpClient = new MastraMCPClient({
+      name,
+      server: config,
+    });
+
+    this.mcpClientsById.set(name, mcpClient);
+    try {
+      await mcpClient.connect();
+    } catch (e) {
+      this.mcpClientsById.delete(name);
+      this.logger.error(`MCPConfiguraiton errored connecting to MCP server ${name}`);
+      throw e;
+    }
+
+    this.logger.debug(`Connected to ${name} MCP server`);
+
+    return mcpClient;
+  }
+
+  private async eachClientTools(
+    cb: (input: {
+      serverName: string;
+      tools: Record<string, any>; // <- any because we don't have proper tool schemas
+      client: InstanceType<typeof MastraMCPClient>;
+    }) => Promise<void>,
+  ) {
+    for (const [serverName, serverConfig] of Object.entries(this.serverConfigs)) {
+      const client = await this.getConnectedClient(serverName, serverConfig);
+      const tools = await client.tools();
+      await cb({
+        serverName,
+        tools,
+        client,
+      });
+    }
+  }
+}

package/src/index.ts

@@ -1 +1,2 @@
 export * from './client';
+export * from './configuration';