{"record":{"id":"7f099e586e70afe0","repo":"microsoft/autogen","slug":"failed-to-call-mcp-tool","errorCode":null,"errorMessage":"Failed to call MCP tool","messagePattern":"Failed to call MCP tool","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-studio/frontend/src/components/views/mcp/api.ts","lineNumber":232,"sourceCode":"\n  async callTool(\n    serverParams: McpServerParams,\n    toolName: string,\n    toolArguments: Record<string, any>\n  ): Promise<CallToolResponse> {\n    const response = await fetch(`${this.getBaseUrl()}/mcp/tools/call`, {\n      method: \"POST\",\n      headers: this.getHeaders(),\n      body: JSON.stringify({\n        server_params: serverParams,\n        tool_name: toolName,\n        arguments: toolArguments,\n      }),\n    });\n\n    const data = await response.json();\n    if (!response.ok) {\n      throw new Error(data.message || \"Failed to call MCP tool\");\n    }\n\n    return data;\n  }\n\n  async healthCheck(): Promise<{ status: boolean; message: string }> {\n    const response = await fetch(`${this.getBaseUrl()}/mcp/health`, {\n      method: \"GET\",\n      headers: this.getHeaders(),\n    });\n\n    const data = await response.json();\n    if (!response.ok) {\n      throw new Error(data.message || \"MCP health check failed\");\n    }\n\n    return data;\n  }","sourceCodeStart":214,"sourceCodeEnd":250,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-studio/frontend/src/components/views/mcp/api.ts#L214-L250","documentation":"Thrown by McpAPI.callTool when POST /mcp/tools/call fails with a non-2xx status. The backend attempted to invoke the named tool on the MCP server described by server_params and something failed: connection, tool discovery, or tool execution. The client only relays data.message or falls back to the generic string.","triggerScenarios":"POST {base}/mcp/tools/call with server_params + tool_name + arguments returning 4xx/5xx: unknown tool_name, arguments that fail the tool's input schema validation, MCP server crashed/stdio command failed, auth failure (401/403), or malformed server_params.","commonSituations":"Tool name typo'd or removed after a server upgrade, arguments not matching the MCP tool's JSON schema (missing required fields, wrong types), stale server_params cached in a saved gallery component after the server config changed, expired auth token.","solutions":["Inspect the response body in DevTools — data.message from the backend usually names the tool or validation error","Re-run listTools for the same server_params and confirm tool_name exists and its input schema matches your arguments object exactly","Validate arguments against the tool's inputSchema before calling (required fields, types)","If 401/403, refresh the auth token and retry","Check the MCP server process itself is alive (run its command manually on the backend host)"],"exampleFix":"// before\nawait mcpAPI.callTool(serverParams, toolName, args);\n// after\nconst tools = await mcpAPI.listTools(serverParams);\nconst tool = tools.data?.tools?.find(t => t.name === toolName);\nif (!tool) throw new Error(`Tool '${toolName}' not offered by this MCP server`);\nawait mcpAPI.callTool(serverParams, toolName, args);","handlingStrategy":"try-catch","validationCode":"// verify tool exists and arguments satisfy its schema before calling\nconst { tools } = (await mcpAPI.listTools(serverParams)).data;\nconst tool = tools.find(t => t.name === toolName);\nif (!tool) throw new Error(`Unknown tool: ${toolName}`);\nconst missing = (tool.inputSchema?.required ?? []).filter(k => !(k in toolArguments));\nif (missing.length) throw new Error(`Missing required args: ${missing.join(\", \")}`);","typeGuard":"function isCallToolResponse(x: unknown): x is CallToolResponse {\n  return !!x && typeof x === \"object\" && \"status\" in x;\n}","tryCatchPattern":"try {\n  const result = await mcpAPI.callTool(serverParams, toolName, args);\n  if (!result.status) return { ok: false, error: result.message };\n  return { ok: true, content: result.data };\n} catch (e) {\n  return { ok: false, error: e instanceof Error ? e.message : String(e) };\n}","preventionTips":["Schema-check arguments against the tool's inputSchema before invoking","Disable tool-call buttons until a fresh listTools confirms the tool exists","Show the backend's data.message, never the generic fallback, in user-facing toasts"],"tags":["mcp","http","fetch","validation","autogen-studio"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}