microsoft/autogen · error · Error

MCP health check failed

Error message

MCP health check failed

What it means

Thrown by McpAPI.healthCheck when GET /mcp/health returns a non-2xx status. This endpoint is the liveness probe for the backend's MCP integration; failure means either the route is not up/authed or the backend's MCP manager failed its self-check. The thrown message is data.message or the generic fallback.

Source

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

    });

    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;
  }

  // Test MCP server connection
  async testMcpConnection(
    workbench: Component<McpWorkbenchConfig>
  ): Promise<boolean> {
    try {
      // Use the health check or list tools to test connection
      if (workbench.config.server_params) {
        const result = await this.listTools(workbench.config.server_params);
        return result.status;
      }
      return false;
    } catch (error) {
      return false;

View on GitHub (pinned to 027ecf0a37)

Solutions

1. curl the backend directly: GET http://<backend>/mcp/health with the Bearer token — isolate proxy vs backend
2. Verify getServerUrl() resolves to the correct base (should include /api prefix when proxied)
3. Re-login to refresh the auth_token if status is 401
4. Confirm the backend version includes the MCP router (check its route table at startup logs)
5. If proxied through a dev server, ensure /mcp/* is in the proxy config, not just /agents or /sessions

// cheap preflight: backend reachable at all?
await fetch(`${getServerUrl()}/mcp/health`, { method: "HEAD" }).catch(() => {
  throw new Error("Backend MCP route unreachable — check server URL / proxy");
});

try {
  return await mcpAPI.healthCheck();
} catch (e) {
  return { status: false, message: e instanceof Error ? e.message : "MCP health check failed" };
}

When it happens

Trigger: GET {base}/mcp/health returning 401/403/404/500: backend route not mounted (version mismatch), auth token missing/expired, API proxy not forwarding /mcp/health, or backend MCP manager raising during its internal check.

Common situations: Frontend served separately from backend so /mcp/health hits the dev server instead of the API, backend version that predates the MCP routes, stale auth_token in localStorage after switching auth backends.

Related errors

• Failed to list MCP tools
• Failed to call MCP tool
• HTTP ${response.status}: ${errorText || "Failed to create We
• Failed to fetch sessions
• Invalid JSON response from server. Check if the MCP route is

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