@mastra/mcp 1.13.1 → 1.14.0-alpha.0

package/dist/index.js

@@ -8,7 +8,7 @@ import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 import { StdioClientTransport, getDefaultEnvironment } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import { DEFAULT_REQUEST_TIMEOUT_MSEC } from '@modelcontextprotocol/sdk/shared/protocol.js';
-import { LoggingMessageNotificationSchema, ListRootsRequestSchema, ListResourcesResultSchema, ReadResourceResultSchema, EmptyResultSchema, ListResourceTemplatesResultSchema, ListPromptsResultSchema, GetPromptResultSchema, PromptListChangedNotificationSchema, ResourceUpdatedNotificationSchema, ResourceListChangedNotificationSchema, ElicitRequestSchema, ProgressNotificationSchema, ListToolsRequestSchema, CallToolRequestSchema, SetLevelRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, McpError, ErrorCode, ListResourceTemplatesRequestSchema, SubscribeRequestSchema, UnsubscribeRequestSchema, ListPromptsRequestSchema, PromptSchema, GetPromptRequestSchema, CallToolResultSchema, JSONRPCMessageSchema } from '@modelcontextprotocol/sdk/types.js';
+import { LoggingMessageNotificationSchema, ListRootsRequestSchema, ListResourcesResultSchema, ReadResourceResultSchema, EmptyResultSchema, ListResourceTemplatesResultSchema, ListPromptsResultSchema, GetPromptResultSchema, PromptListChangedNotificationSchema, ToolListChangedNotificationSchema, ResourceUpdatedNotificationSchema, ResourceListChangedNotificationSchema, ElicitRequestSchema, ProgressNotificationSchema, ListToolsRequestSchema, CallToolRequestSchema, SetLevelRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, McpError, ErrorCode, ListResourceTemplatesRequestSchema, SubscribeRequestSchema, UnsubscribeRequestSchema, ListPromptsRequestSchema, PromptSchema, GetPromptRequestSchema, CallToolResultSchema, JSONRPCMessageSchema } from '@modelcontextprotocol/sdk/types.js';
 import { asyncExitHook, gracefulExit } from 'exit-hook';
 import { createHash, randomUUID } from 'crypto';
 import equal from 'fast-deep-equal';
@@ -31484,6 +31484,7 @@ var InternalMastraMCPClient = class extends MastraBase {
   sigHupHandler;
   serverInstructions;
   _roots;
+  hasElicitationCapability;
   requireToolApproval;
   onToolError;
   /** Provides access to resource operations (list, read, subscribe, etc.) */
@@ -31514,13 +31515,13 @@ var InternalMastraMCPClient = class extends MastraBase {
     this.requireToolApproval = server.requireToolApproval;
     this.onToolError = server.onToolError ?? "throw";
     this._roots = server.roots ?? [];
+    this.hasElicitationCapability = capabilities.elicitation !== void 0;
     const hasRoots = this._roots.length > 0 || !!capabilities.roots;
     const clientCapabilities = {
       ...capabilities,
-      // Merge elicitation capabilities instead of overwriting
-      elicitation: {
-        ...capabilities.elicitation ?? {}
-      },
+      // Only advertise elicitation when explicitly configured or when a handler
+      // registers it before connect(). `elicitation: {}` is legacy form support.
+      ...capabilities.elicitation !== void 0 ? { elicitation: { ...capabilities.elicitation } } : {},
       // Auto-enable roots capability if roots are provided
       ...hasRoots ? { roots: { listChanged: true, ...capabilities.roots ?? {} } } : {},
       // Advertise MCP Apps extension support so servers know we can render UI resources
@@ -31935,6 +31936,16 @@ var InternalMastraMCPClient = class extends MastraBase {
       handler();
     });
   }
+  /**
+   * Register a handler to be called when the tool list changes on the server.
+   * Use this to re-fetch tools via `tools()` when notified.
+   */
+  setToolListChangedNotificationHandler(handler) {
+    this.log("debug", "Setting tool list changed notification handler");
+    this.client.setNotificationHandler(ToolListChangedNotificationSchema, () => {
+      handler();
+    });
+  }
   setResourceUpdatedNotificationHandler(handler) {
     this.log("debug", "Setting resource updated notification handler");
     this.client.setNotificationHandler(ResourceUpdatedNotificationSchema, (notification) => {
@@ -31949,6 +31960,17 @@ var InternalMastraMCPClient = class extends MastraBase {
   }
   setElicitationRequestHandler(handler) {
     this.log("debug", "Setting elicitation request handler");
+    if (!this.hasElicitationCapability) {
+      try {
+        this.client.registerCapabilities({ elicitation: { form: {} } });
+        this.hasElicitationCapability = true;
+      } catch (error51) {
+        throw new Error(
+          "Cannot register an elicitation handler after connecting unless elicitation capability was configured before initialization.",
+          { cause: error51 }
+        );
+      }
+    }
     this.client.setRequestHandler(ElicitRequestSchema, async (request) => {
       this.log("debug", `Received elicitation request: ${request.params.message}`);
       return handler(request.params);
@@ -32411,7 +32433,7 @@ To fix this you have three different options:
        */
       onRequest: async (serverName, handler) => {
         try {
-          const internalClient = await this.getConnectedClientForServer(serverName);
+          const internalClient = await this.getClientForServer(serverName);
           return internalClient.elicitation.onRequest(handler);
         } catch (err) {
           throw new MastraError(
@@ -32836,6 +32858,58 @@ To fix this you have three different options:
       }
     };
   }
+  /**
+   * Provides access to tool-related notification operations across all configured servers.
+   *
+   * To fetch tools, use `listTools()` or `listToolsets()`.
+   *
+   * @example
+   * ```typescript
+   * // React to tool list changes on a server
+   * await mcp.tools.onListChanged('weatherServer', async () => {
+   *   console.log('Tool list changed, re-fetching...');
+   *   const tools = await mcp.listTools();
+   * });
+   * ```
+   */
+  get tools() {
+    this.addToInstanceCache();
+    return {
+      /**
+       * Sets a notification handler for when the tool list changes on a server.
+       *
+       * @param serverName - Name of the server to monitor
+       * @param handler - Callback function invoked when tools are added/removed/modified
+       * @returns Promise resolving when handler is registered
+       * @throws {MastraError} If setting up the handler fails
+       *
+       * @example
+       * ```typescript
+       * await mcp.tools.onListChanged('weatherServer', async () => {
+       *   const tools = await mcp.listTools();
+       * });
+       * ```
+       */
+      onListChanged: async (serverName, handler) => {
+        try {
+          const internalClient = await this.getConnectedClientForServer(serverName);
+          return internalClient.setToolListChangedNotificationHandler(handler);
+        } catch (error51) {
+          throw new MastraError(
+            {
+              id: "MCP_CLIENT_ON_LIST_CHANGED_TOOLS_FAILED",
+              domain: ErrorDomain.MCP,
+              category: ErrorCategory.THIRD_PARTY,
+              details: {
+                serverName
+              }
+            },
+            error51
+          );
+        }
+      }
+    };
+  }
   addToInstanceCache() {
     if (!mcpClientInstances.has(this.id)) {
       mcpClientInstances.set(this.id, this);
@@ -33127,7 +33201,14 @@ To fix this you have three different options:
     if (!client) return null;
     return client.stderr;
   }
-  async getConnectedClient(name, config2) {
+  getServerConfig(serverName) {
+    const serverConfig = this.serverConfigs[serverName];
+    if (!serverConfig) {
+      throw new Error(`Server configuration not found for name: ${serverName}`);
+    }
+    return serverConfig;
+  }
+  async getOrCreateClient(name, config2) {
     if (this.disconnectPromise) {
       await this.disconnectPromise;
     }
@@ -33138,10 +33219,8 @@ To fix this you have three different options:
       if (!existingClient) {
         throw new Error(`Client ${name} exists but is undefined`);
       }
-      await existingClient.connect();
       return existingClient;
     }
-    this.logger.debug("Connecting to MCP server", { name });
     const mcpClient = new InternalMastraMCPClient({
       name,
       server: config2,
@@ -33150,35 +33229,42 @@ To fix this you have three different options:
     });
     mcpClient.__setLogger(this.logger);
     this.mcpClientsById.set(name, mcpClient);
+    return mcpClient;
+  }
+  async getConnectedClient(name, config2) {
+    this.logger.debug("Connecting to MCP server", { name });
+    const mcpClient = await this.getOrCreateClient(name, config2);
     try {
       await mcpClient.connect();
     } catch (e) {
-      const mastraError = new MastraError(
-        {
-          id: "MCP_CLIENT_CONNECT_FAILED",
-          domain: ErrorDomain.MCP,
-          category: ErrorCategory.THIRD_PARTY,
-          text: `Failed to connect to MCP server ${name}: ${e instanceof Error ? e.stack || e.message : String(e)}`,
-          details: {
-            name
-          }
-        },
-        e
-      );
-      this.logger.trackException(mastraError);
-      this.logger.error("MCPClient errored connecting to MCP server:", { error: mastraError.toString() });
-      this.mcpClientsById.delete(name);
-      throw mastraError;
+      throw this.handleConnectError(name, e);
     }
     this.logger.debug("Connected to MCP server", { name });
     return mcpClient;
   }
+  handleConnectError(name, error51) {
+    const mastraError = new MastraError(
+      {
+        id: "MCP_CLIENT_CONNECT_FAILED",
+        domain: ErrorDomain.MCP,
+        category: ErrorCategory.THIRD_PARTY,
+        text: `Failed to connect to MCP server ${name}: ${error51 instanceof Error ? error51.stack || error51.message : String(error51)}`,
+        details: {
+          name
+        }
+      },
+      error51
+    );
+    this.logger.trackException(mastraError);
+    this.logger.error("MCPClient errored connecting to MCP server:", { error: mastraError.toString() });
+    this.mcpClientsById.delete(name);
+    return mastraError;
+  }
   async getConnectedClientForServer(serverName) {
-    const serverConfig = this.serverConfigs[serverName];
-    if (!serverConfig) {
-      throw new Error(`Server configuration not found for name: ${serverName}`);
-    }
-    return this.getConnectedClient(serverName, serverConfig);
+    return this.getConnectedClient(serverName, this.getServerConfig(serverName));
+  }
+  async getClientForServer(serverName) {
+    return this.getOrCreateClient(serverName, this.getServerConfig(serverName));
   }
   async getToolsForServer(serverName) {
     for (let attempt = 1; attempt <= TOOL_DISCOVERY_MAX_ATTEMPTS; attempt++) {
@@ -33643,16 +33729,55 @@ var SSETransport = class {
     });
   }
 };
+async function broadcastNotification({
+  servers,
+  send,
+  logger,
+  errorId,
+  errorText,
+  errorDetails
+}) {
+  const errors = [];
+  for (const server of servers) {
+    try {
+      await send(server);
+    } catch (error51) {
+      errors.push(error51);
+    }
+  }
+  if (errors.length === 0) return;
+  const mastraError = new MastraError(
+    {
+      id: errorId,
+      domain: ErrorDomain.MCP,
+      category: ErrorCategory.THIRD_PARTY,
+      text: errorText,
+      details: {
+        ...errorDetails,
+        failedInstances: errors.length,
+        totalInstances: servers.length
+      }
+    },
+    errors[0]
+  );
+  logger.error(`${errorText}:`, { error: mastraError.toString() });
+  if (errors.length === servers.length) {
+    logger.trackException(mastraError);
+    throw mastraError;
+  }
+}
+
+// src/server/promptActions.ts
 var ServerPromptActions = class {
   getLogger;
-  getSdkServer;
+  getSdkServers;
   clearDefinedPrompts;
   /**
    * @internal
    */
   constructor(dependencies) {
     this.getLogger = dependencies.getLogger;
-    this.getSdkServer = dependencies.getSdkServer;
+    this.getSdkServers = dependencies.getSdkServers;
     this.clearDefinedPrompts = dependencies.clearDefinedPrompts;
   }
   /**
@@ -33661,7 +33786,7 @@ var ServerPromptActions = class {
    * This clears the internal prompt cache and sends a `notifications/prompts/list_changed`
    * message to all clients, prompting them to re-fetch the prompt list.
    *
-   * @throws {MastraError} If sending the notification fails
+   * @throws {MastraError} If sending the notification fails on all server instances
    *
    * @example
    * ```typescript
@@ -33672,47 +33797,39 @@ var ServerPromptActions = class {
   async notifyListChanged() {
     this.getLogger().info("Prompt list change externally notified. Clearing definedPrompts and sending notification.");
     this.clearDefinedPrompts();
-    try {
-      await this.getSdkServer().sendPromptListChanged();
-    } catch (error51) {
-      const mastraError = new MastraError(
-        {
-          id: "MCP_SERVER_PROMPT_LIST_CHANGED_NOTIFICATION_FAILED",
-          domain: ErrorDomain.MCP,
-          category: ErrorCategory.THIRD_PARTY,
-          text: "Failed to send prompt list changed notification"
-        },
-        error51
-      );
-      this.getLogger().error("Failed to send prompt list changed notification:", {
-        error: mastraError.toString()
-      });
-      this.getLogger().trackException(mastraError);
-      throw mastraError;
-    }
+    await broadcastNotification({
+      servers: this.getSdkServers(),
+      send: (server) => server.sendPromptListChanged(),
+      logger: this.getLogger(),
+      errorId: "MCP_SERVER_PROMPT_LIST_CHANGED_NOTIFICATION_FAILED",
+      errorText: "Failed to send prompt list changed notification"
+    });
   }
 };
+
+// src/server/resourceActions.ts
 var ServerResourceActions = class {
-  getSubscriptions;
+  getSubscribedServers;
   getLogger;
-  getSdkServer;
+  getSdkServers;
   /**
    * @internal
    */
   constructor(dependencies) {
-    this.getSubscriptions = dependencies.getSubscriptions;
+    this.getSubscribedServers = dependencies.getSubscribedServers;
     this.getLogger = dependencies.getLogger;
-    this.getSdkServer = dependencies.getSdkServer;
+    this.getSdkServers = dependencies.getSdkServers;
   }
   /**
    * Notifies subscribed clients that a specific resource has been updated.
    *
-   * If clients are subscribed to the resource URI, they will receive a
-   * `notifications/resources/updated` message to re-fetch the resource content.
+   * Only clients that subscribed to the resource URI (via `resources/subscribe`)
+   * receive a `notifications/resources/updated` message prompting them to
+   * re-fetch the resource content.
    *
    * @param params - Notification parameters
    * @param params.uri - URI of the resource that was updated
-   * @throws {MastraError} If sending the notification fails
+   * @throws {MastraError} If sending the notification fails on all subscribed server instances
    *
    * @example
    * ```typescript
@@ -33721,32 +33838,20 @@ var ServerResourceActions = class {
    * ```
    */
   async notifyUpdated({ uri }) {
-    if (this.getSubscriptions().has(uri)) {
-      this.getLogger().info(`Sending notifications/resources/updated for externally notified resource: ${uri}`);
-      try {
-        await this.getSdkServer().sendResourceUpdated({ uri });
-      } catch (error51) {
-        const mastraError = new MastraError(
-          {
-            id: "MCP_SERVER_RESOURCE_UPDATED_NOTIFICATION_FAILED",
-            domain: ErrorDomain.MCP,
-            category: ErrorCategory.THIRD_PARTY,
-            text: "Failed to send resource updated notification",
-            details: {
-              uri
-            }
-          },
-          error51
-        );
-        this.getLogger().trackException(mastraError);
-        this.getLogger().error("Failed to send resource updated notification:", {
-          error: mastraError.toString()
-        });
-        throw mastraError;
-      }
-    } else {
+    const subscribedServers = this.getSubscribedServers(uri);
+    if (subscribedServers.length === 0) {
       this.getLogger().debug(`Resource ${uri} was updated, but no active subscriptions for it.`);
+      return;
     }
+    this.getLogger().info(`Sending notifications/resources/updated for externally notified resource: ${uri}`);
+    await broadcastNotification({
+      servers: subscribedServers,
+      send: (server) => server.sendResourceUpdated({ uri }),
+      logger: this.getLogger(),
+      errorId: "MCP_SERVER_RESOURCE_UPDATED_NOTIFICATION_FAILED",
+      errorText: "Failed to send resource updated notification",
+      errorDetails: { uri }
+    });
   }
   /**
    * Notifies clients that the overall list of available resources has changed.
@@ -33755,7 +33860,7 @@ var ServerResourceActions = class {
    * them to re-fetch the resource list. Resource lists and templates are always evaluated
    * per request, so there is no server-side cache to clear.
    *
-   * @throws {MastraError} If sending the notification fails
+   * @throws {MastraError} If sending the notification fails on all server instances
    *
    * @example
    * ```typescript
@@ -33765,28 +33870,110 @@ var ServerResourceActions = class {
    */
   async notifyListChanged() {
     this.getLogger().info("Resource list change externally notified. Sending notification.");
-    try {
-      await this.getSdkServer().sendResourceListChanged();
-    } catch (error51) {
-      const mastraError = new MastraError(
-        {
-          id: "MCP_SERVER_RESOURCE_LIST_CHANGED_NOTIFICATION_FAILED",
-          domain: ErrorDomain.MCP,
-          category: ErrorCategory.THIRD_PARTY,
-          text: "Failed to send resource list changed notification"
-        },
-        error51
-      );
-      this.getLogger().trackException(mastraError);
-      this.getLogger().error("Failed to send resource list changed notification:", {
-        error: mastraError.toString()
-      });
-      throw mastraError;
+    await broadcastNotification({
+      servers: this.getSdkServers(),
+      send: (server) => server.sendResourceListChanged(),
+      logger: this.getLogger(),
+      errorId: "MCP_SERVER_RESOURCE_LIST_CHANGED_NOTIFICATION_FAILED",
+      errorText: "Failed to send resource list changed notification"
+    });
+  }
+};
+
+// src/server/toolActions.ts
+var ServerToolActions = class {
+  getLogger;
+  getSdkServers;
+  addTools;
+  removeTools;
+  /**
+   * @internal
+   */
+  constructor(dependencies) {
+    this.getLogger = dependencies.getLogger;
+    this.getSdkServers = dependencies.getSdkServers;
+    this.addTools = dependencies.addTools;
+    this.removeTools = dependencies.removeTools;
+  }
+  /**
+   * Registers new tools on the running server and notifies connected clients
+   * that the tool list has changed.
+   *
+   * Tools are keyed by their record key, the same as tools passed to the
+   * `MCPServer` constructor. Adding a tool under an existing key replaces it.
+   *
+   * @param tools - Tools to register
+   * @throws {MastraError} If sending the notification fails on all server instances
+   *
+   * @example
+   * ```typescript
+   * await server.toolActions.add({ myNewTool });
+   * ```
+   */
+  async add(tools) {
+    this.addTools(tools);
+    await this.notifyListChanged();
+  }
+  /**
+   * Removes tools from the running server and notifies connected clients that
+   * the tool list has changed.
+   *
+   * Unknown tool IDs are ignored (logged as a warning). If no tools were
+   * actually removed, no notification is sent.
+   *
+   * @param toolIds - IDs of the tools to remove
+   * @throws {MastraError} If sending the notification fails on all server instances
+   *
+   * @example
+   * ```typescript
+   * await server.toolActions.remove(['myNewTool']);
+   * ```
+   */
+  async remove(toolIds) {
+    const removed = this.removeTools(toolIds);
+    if (removed.length === 0) {
+      this.getLogger().debug("No tools were removed; skipping tool list changed notification.");
+      return;
     }
+    await this.notifyListChanged();
+  }
+  /**
+   * Notifies clients that the overall list of available tools has changed.
+   *
+   * This sends a `notifications/tools/list_changed` message to all clients,
+   * prompting them to re-fetch the tool list.
+   *
+   * @throws {MastraError} If sending the notification fails on all server instances
+   *
+   * @example
+   * ```typescript
+   * // After changing which tools are available
+   * await server.toolActions.notifyListChanged();
+   * ```
+   */
+  async notifyListChanged() {
+    this.getLogger().info("Tool list changed. Sending notification.");
+    await broadcastNotification({
+      servers: this.getSdkServers(),
+      send: (server) => server.sendToolListChanged(),
+      logger: this.getLogger(),
+      errorId: "MCP_SERVER_TOOL_LIST_CHANGED_NOTIFICATION_FAILED",
+      errorText: "Failed to send tool list changed notification"
+    });
   }
 };
 
 // src/server/server.ts
+var LOG_LEVEL_SEVERITY = {
+  debug: 0,
+  info: 1,
+  notice: 2,
+  warning: 3,
+  error: 4,
+  critical: 5,
+  alert: 6,
+  emergency: 7
+};
 var MCPServer = class extends MCPServerBase {
   server;
   stdioTransport;
@@ -33805,8 +33992,12 @@ var MCPServer = class extends MCPServerBase {
   jsonSchemaValidator;
   mapAuthInfoToUser;
   fga;
-  subscriptions = /* @__PURE__ */ new Set();
-  currentLoggingLevel;
+  // Resource subscriptions per server instance (main + per HTTP session), set via
+  // resources/subscribe. Note: legacy SSE sessions share the main instance, so they
+  // share one subscription set; streamable HTTP sessions are isolated per session.
+  subscriptionsByInstance = /* @__PURE__ */ new WeakMap();
+  // Minimum logging level per server instance (main + per HTTP session), set via logging/setLevel
+  loggingLevels = /* @__PURE__ */ new WeakMap();
   /**
    * Provides methods to notify clients about resource changes.
    *
@@ -33830,6 +34021,24 @@ var MCPServer = class extends MCPServerBase {
    * ```
    */
   prompts;
+  /**
+   * Provides methods to dynamically manage tools and notify clients about
+   * tool list changes. Named `toolActions` because `tools()` is the tool
+   * registry getter inherited from `MCPServerBase`.
+   *
+   * @example
+   * ```typescript
+   * // Register a new tool at runtime and notify clients
+   * await server.toolActions.add({ myNewTool });
+   *
+   * // Remove a tool and notify clients
+   * await server.toolActions.remove(['myNewTool']);
+   *
+   * // Notify that the tool list changed (e.g. authorization changes)
+   * await server.toolActions.notifyListChanged();
+   * ```
+   */
+  toolActions;
   /**
    * Provides methods for interactive user input collection during tool execution.
    *
@@ -33947,7 +34156,7 @@ var MCPServer = class extends MCPServerBase {
     this.mapAuthInfoToUser = opts.mapAuthInfoToUser;
     this.fga = opts.fga;
     const capabilities = {
-      tools: {},
+      tools: { listChanged: true },
       logging: { enabled: true }
     };
     if (this.resourceOptions) {
@@ -33986,23 +34195,144 @@ var MCPServer = class extends MCPServerBase {
     this.sseHonoTransports = /* @__PURE__ */ new Map();
     this.registerHandlersOnServer(this.server);
     this.resources = new ServerResourceActions({
-      getSubscriptions: () => this.subscriptions,
+      getSubscribedServers: (uri) => this.getAllSdkServers().filter((server) => this.subscriptionsByInstance.get(server)?.has(uri)),
       getLogger: () => this.logger,
-      getSdkServer: () => this.server
+      getSdkServers: () => this.getAllSdkServers()
     });
     this.prompts = new ServerPromptActions({
       getLogger: () => this.logger,
-      getSdkServer: () => this.server,
+      getSdkServers: () => this.getAllSdkServers(),
       clearDefinedPrompts: () => {
         this.definedPrompts = void 0;
       }
     });
+    this.toolActions = new ServerToolActions({
+      getLogger: () => this.logger,
+      getSdkServers: () => this.getAllSdkServers(),
+      addTools: (tools) => this.addTools(tools),
+      removeTools: (toolIds) => this.removeTools(toolIds)
+    });
     this.elicitation = {
       sendRequest: async (request, options) => {
         return this.handleElicitationRequest(request, void 0, options);
       }
     };
   }
+  /**
+   * Returns every connected SDK server instance: the main instance (stdio/SSE
+   * transports) plus one instance per streamable HTTP session. Used to
+   * broadcast notifications to all connected clients. Instances without a
+   * connected transport are skipped.
+   *
+   * Note: stateless/serverless requests use transient server instances and
+   * cannot receive notifications.
+   */
+  getAllSdkServers() {
+    return [this.server, ...this.httpServerInstances.values()].filter((server) => server.transport !== void 0);
+  }
+  /**
+   * Determines whether a log message at the given level should be sent to the
+   * client connected to the given server instance, honoring the minimum level
+   * the client set via `logging/setLevel` (RFC 5424 severity ordering).
+   * When the client never set a level, all messages are sent.
+   */
+  shouldSendLog(serverInstance, level) {
+    const minimumLevel = this.loggingLevels.get(serverInstance);
+    if (minimumLevel === void 0) return true;
+    return LOG_LEVEL_SEVERITY[level] >= LOG_LEVEL_SEVERITY[minimumLevel];
+  }
+  /**
+   * Sends a `notifications/message` log notification to connected clients.
+   *
+   * The notification is broadcast to every active server instance, honoring
+   * the minimum logging level each client set via `logging/setLevel`.
+   *
+   * @param params - Log message parameters
+   * @param params.level - Log severity level
+   * @param params.data - Arbitrary JSON-serializable data to log
+   * @param params.logger - Optional logger name
+   * @throws {MastraError} If sending the notification fails on all eligible server instances
+   *
+   * @example
+   * ```typescript
+   * await server.sendLoggingMessage({
+   *   level: 'info',
+   *   data: { message: 'Sync completed', itemsProcessed: 42 },
+   * });
+   * ```
+   */
+  async sendLoggingMessage(params) {
+    const eligibleServers = this.getAllSdkServers().filter((server) => this.shouldSendLog(server, params.level));
+    if (eligibleServers.length === 0) {
+      this.logger.debug("No eligible clients for log message; skipping.", { level: params.level });
+      return;
+    }
+    await broadcastNotification({
+      servers: eligibleServers,
+      send: (server) => server.sendLoggingMessage(params),
+      logger: this.logger,
+      errorId: "MCP_SERVER_LOGGING_MESSAGE_NOTIFICATION_FAILED",
+      errorText: "Failed to send logging message notification",
+      errorDetails: { level: params.level }
+    });
+  }
+  /**
+   * Registers new tools on the running server. Tools are merged into both the
+   * converted tool registry (used by list/call handlers) and the original
+   * tools config so they survive tool re-conversion when the server is
+   * registered with a Mastra instance.
+   */
+  addTools(tools) {
+    const converted = this.convertTools(tools);
+    for (const key of Object.keys(converted)) {
+      if (this.convertedTools[key]) {
+        this.logger.warn(`Tool '${key}' already exists and will be replaced.`);
+      }
+    }
+    this.convertedTools = { ...this.convertedTools, ...converted };
+    this.originalTools = { ...this.originalTools, ...tools };
+    if (this.mastra) {
+      for (const [key, tool] of Object.entries(tools)) {
+        if (tool && typeof tool === "object" && "id" in tool) {
+          this.mastra.addTool(tool, this.mastraToolKey(key, tool));
+        }
+      }
+    }
+  }
+  /**
+   * Removes tools from the running server by tool ID.
+   *
+   * @returns The IDs of the tools that were actually removed
+   */
+  removeTools(toolIds) {
+    const removed = [];
+    const convertedTools = { ...this.convertedTools };
+    const originalTools = { ...this.originalTools };
+    for (const toolId of toolIds) {
+      if (convertedTools[toolId]) {
+        const originalTool = originalTools[toolId];
+        delete convertedTools[toolId];
+        delete originalTools[toolId];
+        removed.push(toolId);
+        if (this.mastra && originalTool && typeof originalTool === "object" && "id" in originalTool) {
+          this.mastra.removeTool(this.mastraToolKey(toolId, originalTool));
+        }
+      } else {
+        this.logger.warn(`Cannot remove tool '${toolId}': tool not found.`);
+      }
+    }
+    this.convertedTools = convertedTools;
+    this.originalTools = originalTools;
+    return removed;
+  }
+  /**
+   * The key a tool is registered under in the Mastra instance's tool
+   * registry: the tool's intrinsic ID when present (avoids collisions across
+   * MCP servers), falling back to its record key. Mirrors __registerMastra.
+   */
+  mastraToolKey(key, tool) {
+    return "id" in tool && typeof tool.id === "string" ? tool.id : key;
+  }
   /**
    * Handle an elicitation request by sending it to the connected client.
    * This method sends an elicitation/create request to the client and waits for the response.
@@ -34135,7 +34465,7 @@ var MCPServer = class extends MCPServerBase {
    */
   createServerInstance() {
     const capabilities = {
-      tools: {},
+      tools: { listChanged: true },
       logging: { enabled: true }
     };
     if (this.resourceOptions) {
@@ -34254,6 +34584,33 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
           }
         };
         const proxiedContext = await this.createProxiedRequestContext(extra);
+        const sessionLog = async (level, message, data) => {
+          if (!this.shouldSendLog(serverInstance, level)) return;
+          await extra.sendNotification({
+            method: "notifications/message",
+            params: {
+              level,
+              logger: this.name,
+              data: { message, ...data }
+            }
+          });
+        };
+        const progressToken = extra._meta?.progressToken;
+        const sessionProgress = async (params) => {
+          if (progressToken === void 0) {
+            this.logger.debug("Tool attempted to send progress but the caller sent no progressToken; skipping.", {
+              tool: request.params.name
+            });
+            return;
+          }
+          await extra.sendNotification({
+            method: "notifications/progress",
+            params: {
+              progressToken,
+              ...params
+            }
+          });
+        };
         const mcpOptions = {
           messages: [],
           toolCallId: "",
@@ -34261,7 +34618,9 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
           // Pass MCP-specific context through the mcp property
           mcp: {
             elicitation: sessionElicitation,
-            extra
+            extra,
+            log: sessionLog,
+            progress: sessionProgress
           },
           // @ts-expect-error this is to let people know that the elicitation and extra keys are now nested under mcp.elicitation and mcp.extra in tool arguments
           get elicitation() {
@@ -34349,7 +34708,7 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
       }
     });
     serverInstance.setRequestHandler(SetLevelRequestSchema, async (request) => {
-      this.currentLoggingLevel = request.params.level;
+      this.loggingLevels.set(serverInstance, request.params.level);
       this.logger.debug("Logging level set", { level: request.params.level });
       return {};
     });
@@ -34393,11 +34752,13 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
         try {
           const resourcesOrResourceContent = await capturedResourceOptions.getResourceContent({ uri, extra });
           const resourcesContent = Array.isArray(resourcesOrResourceContent) ? resourcesOrResourceContent : [resourcesOrResourceContent];
+          const resourceMeta = resource._meta ? { _meta: resource._meta } : {};
           const contents = resourcesContent.map((resourceContent) => {
             if ("text" in resourceContent && resourceContent.text !== void 0) {
               return {
                 uri: resource.uri,
                 mimeType: resource.mimeType,
+                ...resourceMeta,
                 text: resourceContent.text
               };
             }
@@ -34408,6 +34769,7 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
             return {
               uri: resource.uri,
               mimeType: resource.mimeType,
+              ...resourceMeta,
               blob
             };
           });
@@ -34438,13 +34800,18 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
     serverInstance.setRequestHandler(SubscribeRequestSchema, async (request) => {
       const uri = request.params.uri;
       this.logger.info("Received resources/subscribe request", { uri });
-      this.subscriptions.add(uri);
+      let subscriptions = this.subscriptionsByInstance.get(serverInstance);
+      if (!subscriptions) {
+        subscriptions = /* @__PURE__ */ new Set();
+        this.subscriptionsByInstance.set(serverInstance, subscriptions);
+      }
+      subscriptions.add(uri);
       return {};
     });
     serverInstance.setRequestHandler(UnsubscribeRequestSchema, async (request) => {
       const uri = request.params.uri;
       this.logger.info("Received resources/unsubscribe request", { uri });
-      this.subscriptions.delete(uri);
+      this.subscriptionsByInstance.get(serverInstance)?.delete(uri);
       return {};
     });
   }
@@ -35014,7 +35381,8 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
     const isStatelessMode = options?.serverless || options && "sessionIdGenerator" in options && options.sessionIdGenerator === void 0;
     if (isStatelessMode) {
       this.logger.debug("Running in stateless mode");
-      await this.handleServerlessRequest(req, res);
+      const enableJsonResponse = options?.enableJsonResponse ?? !options?.serverlessStreaming;
+      await this.handleServerlessRequest(req, res, { enableJsonResponse });
       return;
     }
     const mergedOptions = {
@@ -35058,11 +35426,14 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
           const { isInitializeRequest } = await import('@modelcontextprotocol/sdk/types.js');
           if (isInitializeRequest(body)) {
             this.logger.debug("Received initialize request, creating new transport");
+            const sessionServerInstance = this.createServerInstance();
             transport = new StreamableHTTPServerTransport({
               ...mergedOptions,
               sessionIdGenerator: mergedOptions.sessionIdGenerator,
               onsessioninitialized: (id) => {
                 this.streamableHTTPTransports.set(id, transport);
+                this.httpServerInstances.set(id, sessionServerInstance);
+                this.logger.debug("Session initialized and stored", { sessionId: id });
               }
             });
             transport.onclose = () => {
@@ -35076,15 +35447,7 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
                 }
               }
             };
-            const sessionServerInstance = this.createServerInstance();
             await sessionServerInstance.connect(transport);
-            if (transport.sessionId) {
-              this.streamableHTTPTransports.set(transport.sessionId, transport);
-              this.httpServerInstances.set(transport.sessionId, sessionServerInstance);
-              this.logger.debug("Session initialized and stored", { sessionId: transport.sessionId });
-            } else {
-              this.logger.warn("Transport initialized without a session ID");
-            }
             return await transport.handleRequest(req, res, body);
           } else {
             this.logger.warn("Received non-initialize POST request without session ID");
@@ -35155,21 +35518,26 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
    *
    * @param req - Incoming HTTP request
    * @param res - HTTP response object
+   * @param options - Transport options for this request
+   * @param options.enableJsonResponse - When `true` (default), buffers and returns a single
+   *   JSON-RPC response. When `false`, the request is handled with request-scoped SSE streaming,
+   *   so in-request `notifications/progress` reach the client before the final result.
    * @private
    */
-  async handleServerlessRequest(req, res) {
+  async handleServerlessRequest(req, res, { enableJsonResponse = true } = {}) {
     try {
       this.logger.debug("Received serverless request", { method: req.method });
       const body = req.method === "POST" ? await this.readJsonBody(req) : void 0;
       this.logger.debug("Processing serverless request", {
         method: req.method,
         bodyMethod: body?.method,
-        id: body?.id
+        id: body?.id,
+        enableJsonResponse
       });
       const transientServer = this.createServerInstance();
       const tempTransport = new StreamableHTTPServerTransport({
         sessionIdGenerator: void 0,
-        enableJsonResponse: true
+        enableJsonResponse
       });
       await transientServer.connect(tempTransport);
       await tempTransport.handleRequest(req, res, body);