{"record":{"id":"0bef333e64b53416","repo":"mastra-ai/mastra","slug":"tool-toolid-not-found-on-remote-mcp-server","errorCode":null,"errorMessage":"Tool '${toolId}' not found on remote MCP server '${this.name}'","messagePattern":"Tool '(.+?)' not found on remote MCP server '(.+?)'","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/mcp/src/client/server-proxy.ts","lineNumber":150,"sourceCode":"          }\n        | undefined\n      > {\n    if (this._cachedToolList) {\n      return this._cachedToolList.tools.find(t => t.id === toolId || t.name === toolId);\n    }\n    return this.fetchToolList().then(list => list.tools.find(t => t.id === toolId || t.name === toolId));\n  }\n\n  public async executeTool(\n    toolId: string,\n    args: any,\n    _executionContext?: { messages?: any[]; toolCallId?: string },\n  ): Promise<any> {\n    const client = await this.getClient();\n    const tools = await client.tools();\n    const tool = tools[toolId];\n    if (!tool) {\n      throw new Error(`Tool '${toolId}' not found on remote MCP server '${this.name}'`);\n    }\n    if (!tool.execute) {\n      throw new Error(`Tool '${toolId}' on remote MCP server '${this.name}' has no execute method`);\n    }\n    return tool.execute(args, _executionContext as any);\n  }\n\n  public async listResources(): Promise<{\n    resources: Array<{\n      uri: string;\n      name: string;\n      description?: string;\n      mimeType?: string;\n      _meta?: Record<string, unknown>;\n    }>;\n  }> {\n    const client = await this.getClient();\n    const resources = await client.resources.list();","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/mcp/src/client/server-proxy.ts#L132-L168","documentation":"executeTool on MCPClientServerProxy looks up the requested toolId in the tools fetched live from the remote MCP server; if the remote does not expose a tool with that exact name, this error is thrown. It guards against calling tools() and indexing into a registry that simply does not contain the requested tool.","triggerScenarios":"Calling serverProxy.executeTool('toolName', args) where toolName is misspelled, was removed/renamed on the remote server, or the server failed to list the tool (e.g. the server connected but exposes a different tool set than expected).","commonSituations":"Typo in tool id; remote MCP server upgraded and renamed tools; caching stale tool lists; calling a prompt/resource by mistake as if it were a tool; server started with different configuration so the tool isn't registered.","solutions":["Log client.tools() keys and verify the exact toolId exists on the remote server","Fix the toolId spelling to match the remote tool name exactly","Reconnect/restart the MCP server and confirm its configuration exposes the intended tool","Check for server version changes that renamed or removed the tool"],"exampleFix":"// before\nawait proxy.executeTool('fetchWeather', args);\n// after\nconst tools = await proxy.tools();\nif (!('fetch_weather' in tools)) throw new Error(`Available: ${Object.keys(tools).join(', ')}`);\nawait proxy.executeTool('fetch_weather', args);","handlingStrategy":"validation","validationCode":"const tools = await proxy.tools();\nif (!(toolId in tools)) throw new Error(`Tool '${toolId}' not found. Available: ${Object.keys(tools).join(', ')}`);","typeGuard":"function hasTool(tools: Record<string, unknown>, id: string): tools is Record<string, { execute: Function }> & typeof tools {\n  return Object.prototype.hasOwnProperty.call(tools, id);\n}","tryCatchPattern":"try {\n  await proxy.executeTool(toolId, args);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('not found on remote MCP server')) {\n    const available = Object.keys(await proxy.tools());\n    console.error(`Unknown tool '${toolId}'. Available: ${available.join(', ')}`);\n  } else throw e;\n}","preventionTips":["Discover tool ids via client.tools() instead of hardcoding","Log available tool names at startup after connecting","Pin/verify MCP server versions so tool names don't drift","Add a startup check that every expected tool exists"],"tags":["mcp","tool-not-found","client-proxy"],"backgroundTag":"tool-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}