@mastra/mcp 0.10.4 → 0.10.5-alpha.0

package/dist/index.js

@@ -10,6 +10,7 @@ import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSche
 import { asyncExitHook, gracefulExit } from 'exit-hook';
 import { z } from 'zod';
 import { convertJsonSchemaToZod } from 'zod-from-json-schema';
+import { MastraError, ErrorCategory, ErrorDomain } from '@mastra/core/error';
 import equal from 'fast-deep-equal';
 import { v5 } from 'uuid';
 import { randomUUID } from 'crypto';
@@ -609,7 +610,16 @@ To fix this you have three different options:
             const internalClient = await this.getConnectedClientForServer(serverName);
             allResources[serverName] = await internalClient.resources.list();
           } catch (error) {
-            this.logger.error(`Failed to list resources from server ${serverName}`, { error });
+            const mastraError = new MastraError({
+              id: "MCP_CLIENT_LIST_RESOURCES_FAILED",
+              domain: ErrorDomain.MCP,
+              category: ErrorCategory.THIRD_PARTY,
+              details: {
+                serverName
+              }
+            }, error);
+            this.logger.trackException(mastraError);
+            this.logger.error("Failed to list resources from server:", { error: mastraError.toString() });
           }
         }
         return allResources;
@@ -621,30 +631,97 @@ To fix this you have three different options:
             const internalClient = await this.getConnectedClientForServer(serverName);
             allTemplates[serverName] = await internalClient.resources.templates();
           } catch (error) {
-            this.logger.error(`Failed to list resource templates from server ${serverName}`, { error });
+            const mastraError = new MastraError({
+              id: "MCP_CLIENT_LIST_RESOURCE_TEMPLATES_FAILED",
+              domain: ErrorDomain.MCP,
+              category: ErrorCategory.THIRD_PARTY,
+              details: {
+                serverName
+              }
+            }, error);
+            this.logger.trackException(mastraError);
+            this.logger.error("Failed to list resource templates from server:", { error: mastraError.toString() });
           }
         }
         return allTemplates;
       },
       read: async (serverName, uri) => {
-        const internalClient = await this.getConnectedClientForServer(serverName);
-        return internalClient.resources.read(uri);
+        try {
+          const internalClient = await this.getConnectedClientForServer(serverName);
+          return internalClient.resources.read(uri);
+        } catch (error) {
+          throw new MastraError({
+            id: "MCP_CLIENT_READ_RESOURCE_FAILED",
+            domain: ErrorDomain.MCP,
+            category: ErrorCategory.THIRD_PARTY,
+            details: {
+              serverName,
+              uri
+            }
+          }, error);
+        }
       },
       subscribe: async (serverName, uri) => {
-        const internalClient = await this.getConnectedClientForServer(serverName);
-        return internalClient.resources.subscribe(uri);
+        try {
+          const internalClient = await this.getConnectedClientForServer(serverName);
+          return internalClient.resources.subscribe(uri);
+        } catch (error) {
+          throw new MastraError({
+            id: "MCP_CLIENT_SUBSCRIBE_RESOURCE_FAILED",
+            domain: ErrorDomain.MCP,
+            category: ErrorCategory.THIRD_PARTY,
+            details: {
+              serverName,
+              uri
+            }
+          }, error);
+        }
       },
       unsubscribe: async (serverName, uri) => {
-        const internalClient = await this.getConnectedClientForServer(serverName);
-        return internalClient.resources.unsubscribe(uri);
+        try {
+          const internalClient = await this.getConnectedClientForServer(serverName);
+          return internalClient.resources.unsubscribe(uri);
+        } catch (err) {
+          throw new MastraError({
+            id: "MCP_CLIENT_UNSUBSCRIBE_RESOURCE_FAILED",
+            domain: ErrorDomain.MCP,
+            category: ErrorCategory.THIRD_PARTY,
+            details: {
+              serverName,
+              uri
+            }
+          }, err);
+        }
       },
       onUpdated: async (serverName, handler) => {
-        const internalClient = await this.getConnectedClientForServer(serverName);
-        return internalClient.resources.onUpdated(handler);
+        try {
+          const internalClient = await this.getConnectedClientForServer(serverName);
+          return internalClient.resources.onUpdated(handler);
+        } catch (err) {
+          throw new MastraError({
+            id: "MCP_CLIENT_ON_UPDATED_RESOURCE_FAILED",
+            domain: ErrorDomain.MCP,
+            category: ErrorCategory.THIRD_PARTY,
+            details: {
+              serverName
+            }
+          }, err);
+        }
       },
       onListChanged: async (serverName, handler) => {
-        const internalClient = await this.getConnectedClientForServer(serverName);
-        return internalClient.resources.onListChanged(handler);
+        try {
+          const internalClient = await this.getConnectedClientForServer(serverName);
+          return internalClient.resources.onListChanged(handler);
+        } catch (err) {
+          throw new MastraError({
+            id: "MCP_CLIENT_ON_LIST_CHANGED_RESOURCE_FAILED",
+            domain: ErrorDomain.MCP,
+            category: ErrorCategory.THIRD_PARTY,
+            details: {
+              serverName
+            }
+          }, err);
+        }
       }
     };
   }
@@ -658,18 +735,50 @@ To fix this you have three different options:
             const internalClient = await this.getConnectedClientForServer(serverName);
             allPrompts[serverName] = await internalClient.prompts.list();
           } catch (error) {
-            this.logger.error(`Failed to list prompts from server ${serverName}`, { error });
+            const mastraError = new MastraError({
+              id: "MCP_CLIENT_LIST_PROMPTS_FAILED",
+              domain: ErrorDomain.MCP,
+              category: ErrorCategory.THIRD_PARTY,
+              details: {
+                serverName
+              }
+            }, error);
+            this.logger.trackException(mastraError);
+            this.logger.error("Failed to list prompts from server:", { error: mastraError.toString() });
           }
         }
         return allPrompts;
       },
       get: async ({ serverName, name, args, version }) => {
-        const internalClient = await this.getConnectedClientForServer(serverName);
-        return internalClient.prompts.get({ name, args, version });
+        try {
+          const internalClient = await this.getConnectedClientForServer(serverName);
+          return internalClient.prompts.get({ name, args, version });
+        } catch (error) {
+          throw new MastraError({
+            id: "MCP_CLIENT_GET_PROMPT_FAILED",
+            domain: ErrorDomain.MCP,
+            category: ErrorCategory.THIRD_PARTY,
+            details: {
+              serverName,
+              name
+            }
+          }, error);
+        }
       },
       onListChanged: async (serverName, handler) => {
-        const internalClient = await this.getConnectedClientForServer(serverName);
-        return internalClient.prompts.onListChanged(handler);
+        try {
+          const internalClient = await this.getConnectedClientForServer(serverName);
+          return internalClient.prompts.onListChanged(handler);
+        } catch (error) {
+          throw new MastraError({
+            id: "MCP_CLIENT_ON_LIST_CHANGED_PROMPT_FAILED",
+            domain: ErrorDomain.MCP,
+            category: ErrorCategory.THIRD_PARTY,
+            details: {
+              serverName
+            }
+          }, error);
+        }
       }
     };
   }
@@ -701,21 +810,37 @@ To fix this you have three different options:
   async getTools() {
     this.addToInstanceCache();
     const connectedTools = {};
-    await this.eachClientTools(async ({ serverName, tools }) => {
-      for (const [toolName, toolConfig] of Object.entries(tools)) {
-        connectedTools[`${serverName}_${toolName}`] = toolConfig;
-      }
-    });
+    try {
+      await this.eachClientTools(async ({ serverName, tools }) => {
+        for (const [toolName, toolConfig] of Object.entries(tools)) {
+          connectedTools[`${serverName}_${toolName}`] = toolConfig;
+        }
+      });
+    } catch (error) {
+      throw new MastraError({
+        id: "MCP_CLIENT_GET_TOOLS_FAILED",
+        domain: ErrorDomain.MCP,
+        category: ErrorCategory.THIRD_PARTY
+      }, error);
+    }
     return connectedTools;
   }
   async getToolsets() {
     this.addToInstanceCache();
     const connectedToolsets = {};
-    await this.eachClientTools(async ({ serverName, tools }) => {
-      if (tools) {
-        connectedToolsets[serverName] = tools;
-      }
-    });
+    try {
+      await this.eachClientTools(async ({ serverName, tools }) => {
+        if (tools) {
+          connectedToolsets[serverName] = tools;
+        }
+      });
+    } catch (error) {
+      throw new MastraError({
+        id: "MCP_CLIENT_GET_TOOLSETS_FAILED",
+        domain: ErrorDomain.MCP,
+        category: ErrorCategory.THIRD_PARTY
+      }, error);
+    }
     return connectedToolsets;
   }
   /**
@@ -762,13 +887,19 @@ To fix this you have three different options:
     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);
-      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.stack || e.message : String(e)}`
-      );
+      throw mastraError;
     }
     this.logger.debug(`Connected to ${name} MCP server`);
     return mcpClient;
@@ -882,8 +1013,6 @@ var SSETransport = class {
     });
   }
 };
-
-// src/server/promptActions.ts
 var ServerPromptActions = class {
   getLogger;
   getSdkServer;
@@ -903,15 +1032,23 @@ var ServerPromptActions = class {
     try {
       await this.getSdkServer().sendPromptListChanged();
     } catch (error) {
+      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"
+        },
+        error
+      );
       this.getLogger().error("Failed to send prompt list changed notification:", {
-        error: error instanceof Error ? error.message : String(error)
+        error: mastraError.toString()
       });
-      throw error;
+      this.getLogger().trackException(mastraError);
+      throw mastraError;
     }
   }
 };
-
-// src/server/resourceActions.ts
 var ServerResourceActions = class {
   getSubscriptions;
   getLogger;
@@ -935,8 +1072,23 @@ var ServerResourceActions = class {
       try {
         await this.getSdkServer().sendResourceUpdated({ uri });
       } catch (error) {
-        this.getLogger().error("Failed to send resource updated notification:", { error });
-        throw error;
+        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
+            }
+          },
+          error
+        );
+        this.getLogger().trackException(mastraError);
+        this.getLogger().error("Failed to send resource updated notification:", {
+          error: mastraError.toString()
+        });
+        throw mastraError;
       }
     } else {
       this.getLogger().debug(`Resource ${uri} was updated, but no active subscriptions for it.`);
@@ -955,8 +1107,20 @@ var ServerResourceActions = class {
     try {
       await this.getSdkServer().sendResourceListChanged();
     } catch (error) {
-      this.getLogger().error("Failed to send resource list changed notification:", { error });
-      throw error;
+      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"
+        },
+        error
+      );
+      this.getLogger().trackException(mastraError);
+      this.getLogger().error("Failed to send resource list changed notification:", {
+        error: mastraError.toString()
+      });
+      throw mastraError;
     }
   }
 };
@@ -1234,8 +1398,26 @@ var MCPServer = class extends MCPServerBase {
       this.logger.info(`Registered explicit tool: '${toolName}'`);
     }
     this.logger.info(`Total defined tools registered: ${Object.keys(definedConvertedTools).length}`);
-    const agentDerivedTools = this.convertAgentsToTools(agentsConfig, definedConvertedTools);
-    const workflowDerivedTools = this.convertWorkflowsToTools(workflowsConfig, definedConvertedTools);
+    let agentDerivedTools = {};
+    let workflowDerivedTools = {};
+    try {
+      agentDerivedTools = this.convertAgentsToTools(agentsConfig, definedConvertedTools);
+      workflowDerivedTools = this.convertWorkflowsToTools(workflowsConfig, definedConvertedTools);
+    } catch (e) {
+      const mastraError = new MastraError(
+        {
+          id: "MCP_SERVER_AGENT_OR_WORKFLOW_TOOL_CONVERSION_FAILED",
+          domain: ErrorDomain.MCP,
+          category: ErrorCategory.USER
+        },
+        e
+      );
+      this.logger.trackException(mastraError);
+      this.logger.error("Failed to convert tools:", {
+        error: mastraError.toString()
+      });
+      throw mastraError;
+    }
     const allConvertedTools = { ...definedConvertedTools, ...agentDerivedTools, ...workflowDerivedTools };
     const finalToolCount = Object.keys(allConvertedTools).length;
     const definedCount = Object.keys(definedConvertedTools).length;
@@ -1587,7 +1769,23 @@ var MCPServer = class extends MCPServerBase {
    */
   async startStdio() {
     this.stdioTransport = new StdioServerTransport();
-    await this.server.connect(this.stdioTransport);
+    try {
+      await this.server.connect(this.stdioTransport);
+    } catch (error) {
+      const mastraError = new MastraError(
+        {
+          id: "MCP_SERVER_STDIO_CONNECTION_FAILED",
+          domain: ErrorDomain.MCP,
+          category: ErrorCategory.THIRD_PARTY
+        },
+        error
+      );
+      this.logger.trackException(mastraError);
+      this.logger.error("Failed to connect MCP server using stdio transport:", {
+        error: mastraError.toString()
+      });
+      throw mastraError;
+    }
     this.logger.info("Started MCP Server (stdio)");
   }
   /**
@@ -1601,23 +1799,42 @@ var MCPServer = class extends MCPServerBase {
    * @param res HTTP response (must support .write/.end)
    */
   async startSSE({ url, ssePath, messagePath, req, res }) {
-    if (url.pathname === ssePath) {
-      await this.connectSSE({
-        messagePath,
-        res
-      });
-    } else if (url.pathname === messagePath) {
-      this.logger.debug("Received message");
-      if (!this.sseTransport) {
-        res.writeHead(503);
-        res.end("SSE connection not established");
-        return;
+    try {
+      if (url.pathname === ssePath) {
+        await this.connectSSE({
+          messagePath,
+          res
+        });
+      } else if (url.pathname === messagePath) {
+        this.logger.debug("Received message");
+        if (!this.sseTransport) {
+          res.writeHead(503);
+          res.end("SSE connection not established");
+          return;
+        }
+        await this.sseTransport.handlePostMessage(req, res);
+      } else {
+        this.logger.debug("Unknown path:", { path: url.pathname });
+        res.writeHead(404);
+        res.end();
       }
-      await this.sseTransport.handlePostMessage(req, res);
-    } else {
-      this.logger.debug("Unknown path:", { path: url.pathname });
-      res.writeHead(404);
-      res.end();
+    } catch (e) {
+      const mastraError = new MastraError(
+        {
+          id: "MCP_SERVER_SSE_START_FAILED",
+          domain: ErrorDomain.MCP,
+          category: ErrorCategory.USER,
+          details: {
+            url: url.toString(),
+            ssePath,
+            messagePath
+          }
+        },
+        e
+      );
+      this.logger.trackException(mastraError);
+      this.logger.error("Failed to start MCP Server (SSE):", { error: mastraError.toString() });
+      throw mastraError;
     }
   }
   /**
@@ -1630,31 +1847,50 @@ var MCPServer = class extends MCPServerBase {
    * @param context Incoming Hono context
    */
   async startHonoSSE({ url, ssePath, messagePath, context }) {
-    if (url.pathname === ssePath) {
-      return streamSSE(context, async (stream) => {
-        await this.connectHonoSSE({
-          messagePath,
-          stream
+    try {
+      if (url.pathname === ssePath) {
+        return streamSSE(context, async (stream) => {
+          await this.connectHonoSSE({
+            messagePath,
+            stream
+          });
         });
-      });
-    } else if (url.pathname === messagePath) {
-      this.logger.debug("Received message");
-      const sessionId = context.req.query("sessionId");
-      this.logger.debug("Received message for sessionId", { sessionId });
-      if (!sessionId) {
-        return context.text("No sessionId provided", 400);
-      }
-      if (!this.sseHonoTransports.has(sessionId)) {
-        return context.text(`No transport found for sessionId ${sessionId}`, 400);
-      }
-      const message = await this.sseHonoTransports.get(sessionId)?.handlePostMessage(context);
-      if (!message) {
-        return context.text("Transport not found", 400);
+      } else if (url.pathname === messagePath) {
+        this.logger.debug("Received message");
+        const sessionId = context.req.query("sessionId");
+        this.logger.debug("Received message for sessionId", { sessionId });
+        if (!sessionId) {
+          return context.text("No sessionId provided", 400);
+        }
+        if (!this.sseHonoTransports.has(sessionId)) {
+          return context.text(`No transport found for sessionId ${sessionId}`, 400);
+        }
+        const message = await this.sseHonoTransports.get(sessionId)?.handlePostMessage(context);
+        if (!message) {
+          return context.text("Transport not found", 400);
+        }
+        return message;
+      } else {
+        this.logger.debug("Unknown path:", { path: url.pathname });
+        return context.text("Unknown path", 404);
       }
-      return message;
-    } else {
-      this.logger.debug("Unknown path:", { path: url.pathname });
-      return context.text("Unknown path", 404);
+    } catch (e) {
+      const mastraError = new MastraError(
+        {
+          id: "MCP_SERVER_HONO_SSE_START_FAILED",
+          domain: ErrorDomain.MCP,
+          category: ErrorCategory.USER,
+          details: {
+            url: url.toString(),
+            ssePath,
+            messagePath
+          }
+        },
+        e
+      );
+      this.logger.trackException(mastraError);
+      this.logger.error("Failed to start MCP Server (Hono SSE):", { error: mastraError.toString() });
+      throw mastraError;
     }
   }
   /**
@@ -1783,7 +2019,17 @@ var MCPServer = class extends MCPServerBase {
         }
       }
     } catch (error) {
-      this.logger.error("startHTTP: Error handling Streamable HTTP request:", { error });
+      const mastraError = new MastraError(
+        {
+          id: "MCP_SERVER_HTTP_CONNECTION_FAILED",
+          domain: ErrorDomain.MCP,
+          category: ErrorCategory.USER,
+          text: "Failed to connect MCP server using HTTP transport"
+        },
+        error
+      );
+      this.logger.trackException(mastraError);
+      this.logger.error("startHTTP: Error handling Streamable HTTP request:", { error: mastraError });
       if (!res.headersSent) {
         res.writeHead(500, { "Content-Type": "application/json" });
         res.end(
@@ -1797,8 +2043,6 @@ var MCPServer = class extends MCPServerBase {
             // Cannot determine original request ID in catch
           })
         );
-      } else {
-        this.logger.error("startHTTP: Error after headers sent:", error);
       }
     }
   }
@@ -1806,16 +2050,33 @@ var MCPServer = class extends MCPServerBase {
     messagePath,
     res
   }) {
-    this.logger.debug("Received SSE connection");
-    this.sseTransport = new SSEServerTransport(messagePath, res);
-    await this.server.connect(this.sseTransport);
-    this.server.onclose = async () => {
-      this.sseTransport = void 0;
-      await this.server.close();
-    };
-    res.on("close", () => {
-      this.sseTransport = void 0;
-    });
+    try {
+      this.logger.debug("Received SSE connection");
+      this.sseTransport = new SSEServerTransport(messagePath, res);
+      await this.server.connect(this.sseTransport);
+      this.server.onclose = async () => {
+        this.sseTransport = void 0;
+        await this.server.close();
+      };
+      res.on("close", () => {
+        this.sseTransport = void 0;
+      });
+    } catch (e) {
+      const mastraError = new MastraError(
+        {
+          id: "MCP_SERVER_SSE_CONNECT_FAILED",
+          domain: ErrorDomain.MCP,
+          category: ErrorCategory.USER,
+          details: {
+            messagePath
+          }
+        },
+        e
+      );
+      this.logger.trackException(mastraError);
+      this.logger.error("Failed to connect to MCP Server (SSE):", { error: mastraError });
+      throw mastraError;
+    }
   }
   async connectHonoSSE({ messagePath, stream }) {
     this.logger.debug("Received SSE connection");
@@ -1827,17 +2088,34 @@ var MCPServer = class extends MCPServerBase {
       this.logger.debug("SSE Transport aborted with sessionId:", { sessionId });
       this.sseHonoTransports.delete(sessionId);
     });
-    await this.server.connect(sseTransport);
-    this.server.onclose = async () => {
-      this.logger.debug("SSE Transport closed with sessionId:", { sessionId });
-      this.sseHonoTransports.delete(sessionId);
-      await this.server.close();
-    };
-    while (true) {
-      const sessionIds = Array.from(this.sseHonoTransports.keys() || []);
-      this.logger.debug("Active Hono SSE sessions:", { sessionIds });
-      await stream.write(":keep-alive\n\n");
-      await stream.sleep(6e4);
+    try {
+      await this.server.connect(sseTransport);
+      this.server.onclose = async () => {
+        this.logger.debug("SSE Transport closed with sessionId:", { sessionId });
+        this.sseHonoTransports.delete(sessionId);
+        await this.server.close();
+      };
+      while (true) {
+        const sessionIds = Array.from(this.sseHonoTransports.keys() || []);
+        this.logger.debug("Active Hono SSE sessions:", { sessionIds });
+        await stream.write(":keep-alive\n\n");
+        await stream.sleep(6e4);
+      }
+    } catch (e) {
+      const mastraError = new MastraError(
+        {
+          id: "MCP_SERVER_HONO_SSE_CONNECT_FAILED",
+          domain: ErrorDomain.MCP,
+          category: ErrorCategory.USER,
+          details: {
+            messagePath
+          }
+        },
+        e
+      );
+      this.logger.trackException(mastraError);
+      this.logger.error("Failed to connect to MCP Server (Hono SSE):", { error: mastraError });
+      throw mastraError;
     }
   }
   /**
@@ -1875,7 +2153,17 @@ var MCPServer = class extends MCPServerBase {
       await this.server.close();
       this.logger.info("MCP server closed.");
     } catch (error) {
-      this.logger.error("Error closing MCP server:", { error });
+      const mastraError = new MastraError(
+        {
+          id: "MCP_SERVER_CLOSE_FAILED",
+          domain: ErrorDomain.MCP,
+          category: ErrorCategory.THIRD_PARTY
+        },
+        error
+      );
+      this.logger.trackException(mastraError);
+      this.logger.error("Error closing MCP server:", { error: mastraError });
+      throw mastraError;
     }
   }
   /**
@@ -1953,30 +2241,47 @@ var MCPServer = class extends MCPServerBase {
    */
   async executeTool(toolId, args, executionContext) {
     const tool = this.convertedTools[toolId];
-    if (!tool) {
-      this.logger.warn(`ExecuteTool: Unknown tool '${toolId}' requested on MCPServer '${this.name}'.`);
-      throw new Error(`Unknown tool: ${toolId}`);
-    }
-    this.logger.debug(`ExecuteTool: Invoking '${toolId}' with arguments:`, args);
-    let validatedArgs = args;
-    if (tool.parameters instanceof z.ZodType && typeof tool.parameters.safeParse === "function") {
-      const validation = tool.parameters.safeParse(args ?? {});
-      if (!validation.success) {
-        const errorMessages = validation.error.errors.map((e) => `${e.path.join(".")}: ${e.message}`).join(", ");
-        this.logger.warn(`ExecuteTool: Invalid tool arguments for '${toolId}': ${errorMessages}`, {
-          errors: validation.error.format()
-        });
-        throw new z.ZodError(validation.error.issues);
+    let validatedArgs;
+    try {
+      if (!tool) {
+        this.logger.warn(`ExecuteTool: Unknown tool '${toolId}' requested on MCPServer '${this.name}'.`);
+        throw new Error(`Unknown tool: ${toolId}`);
       }
-      validatedArgs = validation.data;
-    } else {
-      this.logger.debug(
-        `ExecuteTool: Tool '${toolId}' parameters is not a Zod schema with safeParse or is undefined. Skipping validation.`
+      this.logger.debug(`ExecuteTool: Invoking '${toolId}' with arguments:`, args);
+      if (tool.parameters instanceof z.ZodType && typeof tool.parameters.safeParse === "function") {
+        const validation = tool.parameters.safeParse(args ?? {});
+        if (!validation.success) {
+          const errorMessages = validation.error.errors.map((e) => `${e.path.join(".")}: ${e.message}`).join(", ");
+          this.logger.warn(`ExecuteTool: Invalid tool arguments for '${toolId}': ${errorMessages}`, {
+            errors: validation.error.format()
+          });
+          throw new z.ZodError(validation.error.issues);
+        }
+        validatedArgs = validation.data;
+      } else {
+        this.logger.debug(
+          `ExecuteTool: Tool '${toolId}' parameters is not a Zod schema with safeParse or is undefined. Skipping validation.`
+        );
+      }
+      if (!tool.execute) {
+        this.logger.error(`ExecuteTool: Tool '${toolId}' does not have an execute function.`);
+        throw new Error(`Tool '${toolId}' cannot be executed.`);
+      }
+    } catch (error) {
+      const mastraError = new MastraError(
+        {
+          id: "MCP_SERVER_TOOL_EXECUTE_PREPARATION_FAILED",
+          domain: ErrorDomain.MCP,
+          category: ErrorCategory.USER,
+          details: {
+            toolId,
+            args
+          }
+        },
+        error
       );
-    }
-    if (!tool.execute) {
-      this.logger.error(`ExecuteTool: Tool '${toolId}' does not have an execute function.`);
-      throw new Error(`Tool '${toolId}' cannot be executed.`);
+      this.logger.trackException(mastraError);
+      throw mastraError;
     }
     try {
       const finalExecutionContext = {
@@ -1987,8 +2292,21 @@ var MCPServer = class extends MCPServerBase {
       this.logger.info(`ExecuteTool: Tool '${toolId}' executed successfully.`);
       return result;
     } catch (error) {
+      const mastraError = new MastraError(
+        {
+          id: "MCP_SERVER_TOOL_EXECUTE_FAILED",
+          domain: ErrorDomain.MCP,
+          category: ErrorCategory.USER,
+          details: {
+            toolId,
+            validatedArgs
+          }
+        },
+        error
+      );
+      this.logger.trackException(mastraError);
       this.logger.error(`ExecuteTool: Tool execution failed for '${toolId}':`, { error });
-      throw error instanceof Error ? error : new Error(`Execution of tool '${toolId}' failed: ${String(error)}`);
+      throw mastraError;
     }
   }
 };