{"record":{"id":"bdec3c00545e67a4","repo":"mastra-ai/mastra","slug":"server-serverid-cannot-execute-tools-in-this","errorCode":null,"errorMessage":"Server '${serverId}' cannot execute tools in this way.","messagePattern":"Server '(.+?)' cannot execute tools in this way\\.","errorType":"http","errorClass":"HTTPException","httpStatus":501,"severity":"error","filePath":"packages/server/src/server/handlers/mcp.ts","lineNumber":234,"sourceCode":"  handler: async ({\n    mastra,\n    serverId,\n    toolId,\n    data,\n    requestContext,\n  }: ServerContext & { serverId: string; toolId: string; data?: unknown }) => {\n    if (!mastra || typeof mastra.getMCPServerById !== 'function') {\n      throw new HTTPException(500, { message: 'Mastra instance or getMCPServerById method not available' });\n    }\n\n    const server = mastra.getMCPServerById(serverId);\n\n    if (!server) {\n      throw new HTTPException(404, { message: `MCP server with ID '${serverId}' not found` });\n    }\n\n    if (typeof server.executeTool !== 'function') {\n      throw new HTTPException(501, { message: `Server '${serverId}' cannot execute tools in this way.` });\n    }\n\n    const result = await server.executeTool(toolId, data, { requestContext });\n    return { result };\n  },\n});\n\n// ============================================================================\n// MCP Resource Routes\n// ============================================================================\n\nexport const LIST_MCP_SERVER_RESOURCES_ROUTE = createRoute({\n  method: 'GET',\n  path: '/mcp/:serverId/resources',\n  responseType: 'json',\n  pathParamSchema: mcpServerResourcePathParams,\n  responseSchema: listResourcesResponseSchema,\n  summary: 'List MCP server resources',","sourceCodeStart":216,"sourceCodeEnd":252,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/mcp.ts#L216-L252","documentation":"A 501 thrown when the resolved MCP server object exists but has no executeTool method, meaning the server implementation cannot run tools through this HTTP path. It protects against calling execute on a partial/stub server object (e.g. a handle that only exposes discovery or resource APIs).","triggerScenarios":"POST /mcp/:serverId/tools/:toolId/execute where getMCPServerById returns an object whose interface lacks executeTool — typically a custom MCP server wrapper, a stubbed object, or an older/alternative server implementation in @mastra/core/mcp.","commonSituations":"Test doubles for MCP servers missing executeTool; mixing server object types from different @mastra/core versions; wrapping/proxying MCP server objects and dropping methods.","solutions":["Register a real MCPServer instance from @mastra/core/mcp, which implements executeTool.","Update @mastra/core so the registered server class includes executeTool.","If you wrapped or stubbed the server, add/forward executeTool(toolId, data, { requestContext }).","Use a different execution path (direct client/tool call) if the server intentionally does not support remote tool execution."],"exampleFix":"// before\nconst server = { id: 'weather', listResources: async () => [] };\n// after\nimport { MCPServer } from '@mastra/core/mcp';\nconst server = new MCPServer({ id: 'weather' /* full config */ });","handlingStrategy":"type-guard","validationCode":"const server = mastra.getMCPServerById(serverId);\nif (server && typeof (server as any).executeTool !== 'function') {\n  throw new Error(`Server '${serverId}' does not support tool execution via HTTP`);\n}","typeGuard":"function canExecuteTools(server: unknown): server is { executeTool: (toolId: string, data?: unknown, opts?: unknown) => Promise<unknown> } {\n  return !!server && typeof (server as any).executeTool === 'function';\n}","tryCatchPattern":"try {\n  const { result } = await executeMcpTool(serverId, toolId, data);\n} catch (e) {\n  if (e.status === 501) {\n    console.warn(`Server ${serverId} cannot execute tools; use direct MCPServer client instead`);\n    return;\n  }\n  throw e;\n}","preventionTips":["Register genuine MCPServer instances from @mastra/core/mcp, not partial stubs.","Avoid wrapping/proxying server objects in ways that drop methods.","Keep @mastra/core current so server classes implement executeTool."],"tags":["mcp","not-implemented","type-mismatch","version-mismatch"],"backgroundTag":"method-not-implemented","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}