mastra-ai/mastra · error · Error

Tool '${toolId}' not found on remote MCP server '${this.name

Error message

Tool '${toolId}' not found on remote MCP server '${this.name}'

What it means

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.

Source

Thrown at packages/mcp/src/client/server-proxy.ts:150

          }
        | undefined
      > {
    if (this._cachedToolList) {
      return this._cachedToolList.tools.find(t => t.id === toolId || t.name === toolId);
    }
    return this.fetchToolList().then(list => list.tools.find(t => t.id === toolId || t.name === toolId));
  }

  public async executeTool(
    toolId: string,
    args: any,
    _executionContext?: { messages?: any[]; toolCallId?: string },
  ): Promise<any> {
    const client = await this.getClient();
    const tools = await client.tools();
    const tool = tools[toolId];
    if (!tool) {
      throw new Error(`Tool '${toolId}' not found on remote MCP server '${this.name}'`);
    }
    if (!tool.execute) {
      throw new Error(`Tool '${toolId}' on remote MCP server '${this.name}' has no execute method`);
    }
    return tool.execute(args, _executionContext as any);
  }

  public async listResources(): Promise<{
    resources: Array<{
      uri: string;
      name: string;
      description?: string;
      mimeType?: string;
      _meta?: Record<string, unknown>;
    }>;
  }> {
    const client = await this.getClient();
    const resources = await client.resources.list();

View on GitHub (pinned to 75dd419e61)

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

Example fix

// before
await proxy.executeTool('fetchWeather', args);
// after
const tools = await proxy.tools();
if (!('fetch_weather' in tools)) throw new Error(`Available: ${Object.keys(tools).join(', ')}`);
await proxy.executeTool('fetch_weather', args);

Defensive patterns

Strategy: validation

Validate before calling

const tools = await proxy.tools();
if (!(toolId in tools)) throw new Error(`Tool '${toolId}' not found. Available: ${Object.keys(tools).join(', ')}`);

Type guard

function hasTool(tools: Record<string, unknown>, id: string): tools is Record<string, { execute: Function }> & typeof tools {
  return Object.prototype.hasOwnProperty.call(tools, id);
}

Try / catch

try {
  await proxy.executeTool(toolId, args);
} catch (e) {
  if (e instanceof Error && e.message.includes('not found on remote MCP server')) {
    const available = Object.keys(await proxy.tools());
    console.error(`Unknown tool '${toolId}'. Available: ${available.join(', ')}`);
  } else throw e;
}

Prevention

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

When it happens

Trigger: 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).

Common situations: 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.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/0bef333e64b53416. Report an issue: GitHub.