microsoft/autogen · error · Error

Failed to call MCP tool

Error message

Failed to call MCP tool

What it means

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.

Source

Thrown at python/packages/autogen-studio/frontend/src/components/views/mcp/api.ts:232

  async callTool(
    serverParams: McpServerParams,
    toolName: string,
    toolArguments: Record<string, any>
  ): Promise<CallToolResponse> {
    const response = await fetch(`${this.getBaseUrl()}/mcp/tools/call`, {
      method: "POST",
      headers: this.getHeaders(),
      body: JSON.stringify({
        server_params: serverParams,
        tool_name: toolName,
        arguments: toolArguments,
      }),
    });

    const data = await response.json();
    if (!response.ok) {
      throw new Error(data.message || "Failed to call MCP tool");
    }

    return data;
  }

  async healthCheck(): Promise<{ status: boolean; message: string }> {
    const response = await fetch(`${this.getBaseUrl()}/mcp/health`, {
      method: "GET",
      headers: this.getHeaders(),
    });

    const data = await response.json();
    if (!response.ok) {
      throw new Error(data.message || "MCP health check failed");
    }

    return data;
  }

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Inspect the response body in DevTools — data.message from the backend usually names the tool or validation error
2. Re-run listTools for the same server_params and confirm tool_name exists and its input schema matches your arguments object exactly
3. Validate arguments against the tool's inputSchema before calling (required fields, types)
4. If 401/403, refresh the auth token and retry
5. Check the MCP server process itself is alive (run its command manually on the backend host)

Example fix

// before
await mcpAPI.callTool(serverParams, toolName, args);
// after
const tools = await mcpAPI.listTools(serverParams);
const tool = tools.data?.tools?.find(t => t.name === toolName);
if (!tool) throw new Error(`Tool '${toolName}' not offered by this MCP server`);
await mcpAPI.callTool(serverParams, toolName, args);

// verify tool exists and arguments satisfy its schema before calling
const { tools } = (await mcpAPI.listTools(serverParams)).data;
const tool = tools.find(t => t.name === toolName);
if (!tool) throw new Error(`Unknown tool: ${toolName}`);
const missing = (tool.inputSchema?.required ?? []).filter(k => !(k in toolArguments));
if (missing.length) throw new Error(`Missing required args: ${missing.join(", ")}`);

function isCallToolResponse(x: unknown): x is CallToolResponse {
  return !!x && typeof x === "object" && "status" in x;
}

try {
  const result = await mcpAPI.callTool(serverParams, toolName, args);
  if (!result.status) return { ok: false, error: result.message };
  return { ok: true, content: result.data };
} catch (e) {
  return { ok: false, error: e instanceof Error ? e.message : String(e) };
}

When it happens

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

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

Related errors

• Failed to list MCP tools
• MCP health check failed
• HTTP ${response.status}: ${errorText || "Failed to create We
• Failed to fetch sessions
• Failed to validate component

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/7f099e586e70afe0. Report an issue: GitHub.