@cursor/bdk 0.2.1

package/src/internal/cursor/account-mcp.ts

@@ -0,0 +1,692 @@
+/**
+ * The Cursor account MCP bridge: `defineConnection({ cursorAccount: true })`
+ * resolved for local turns.
+ *
+ * The serve host mounts one loopback-only streamable-HTTP MCP route per
+ * authored account MCP connection (`<base>/v1/cursor-account/<name>/mcp`,
+ * guarded by a per-boot bearer secret). The bridge lists and executes the
+ * account's connector tools through the Cursor backend
+ * (`DashboardService.ListSandMcpTools` / `ExecuteSandMcpTool`), which owns
+ * the OAuth credentials — **raw MCP tokens never enter this process**.
+ *
+ * Cloud-runtime turns reach the same bridge through the serve `publicUrl`
+ * (so `servers` filters apply there too); without one they omit the bridge
+ * and fall back to the account's natively hydrated connectors.
+ */
+
+import { randomBytes } from "node:crypto";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { bearerAuth } from "../../channels.js";
+import type { AgentProject, AuthPolicy, McpToolAnnotations } from "../../types.js";
+import { isCursorAccountTransport } from "../../types.js";
+import { probeConnectorAuthUrls } from "../cursor-account-mcp-auth.js";
+import { describeError } from "../describe-error.js";
+import { LOG_PREFIX } from "../distribution.js";
+import { handleStatelessMcpRequest } from "../mcp-endpoint.js";
+import { isLoopbackAddress } from "../net.js";
+import { sanitizeMcpToolName, suffixMcpToolName } from "../sanitize-mcp-tool-name.js";
+import type { EngineResolvedConnection } from "../session-engine.js";
+import {
+  colorEnabledFor,
+  formatTerminalBox,
+  stdoutPalette,
+  type TerminalPalette,
+  terminalHyperlink,
+} from "../terminal-style.js";
+import type {
+  AccountMcpCallResult,
+  AccountMcpServer,
+  CursorBackendClient,
+} from "./backend-client.js";
+
+/** Catalog freshness window; a miss inside it re-uses the cached listing. */
+const CATALOG_TTL_MS = 60_000;
+/**
+ * Unknown-tool lookups force a refresh, but never more often than this —
+ * a model hallucinating tool names cannot turn into a backend hot loop.
+ */
+const FORCE_REFRESH_MIN_INTERVAL_MS = 5_000;
+
+/** Dashboard Integrations & MCP — reconnect team / account connectors. */
+export const CURSOR_ACCOUNT_MCP_DASHBOARD_URL = "https://cursor.com/dashboard/integrations";
+/** Cursor app Settings → MCP (Connect / Authenticate on the named row). */
+export const CURSOR_ACCOUNT_MCP_SETTINGS_DEEPLINK =
+  "cursor://anysphere.cursor-deeplink/customize?tab=mcp";
+
+// ============================================================================
+// Authored account MCP connections (validated refs, mirroring peer MCP connections)
+// ============================================================================
+
+export interface CursorAccountConnectionRef {
+  /** Connection (MCP server) name — the filename under `agent/mcp-connections/`. */
+  name: string;
+  /** Connector-name filter, or undefined for every connected server. */
+  servers?: string[];
+}
+
+/**
+ * Collect `cursorAccount` connections across `mounts`, grouped by mount
+ * slug. Purely structural — per-connector validation happens live against
+ * the account (see {@link CursorAccountMcpBridge.logPreflight}).
+ */
+export function collectCursorAccountConnections(
+  mounts: Array<{ slug: string; project: AgentProject }>,
+): Map<string, CursorAccountConnectionRef[]> {
+  const bySlug = new Map<string, CursorAccountConnectionRef[]>();
+  for (const { slug, project } of mounts) {
+    const refs: CursorAccountConnectionRef[] = [];
+    for (const connection of [
+      ...project.agent.connections,
+      ...(project.agent.hostConnections ?? []),
+    ]) {
+      if (!isCursorAccountTransport(connection.transport)) {
+        continue;
+      }
+      refs.push({
+        name: connection.name,
+        ...(connection.transport.servers === undefined
+          ? {}
+          : { servers: [...connection.transport.servers] }),
+      });
+    }
+    if (refs.length > 0) {
+      bySlug.set(slug, refs);
+    }
+  }
+  return bySlug;
+}
+
+/** Bridge mount path for one account MCP connection, relative to the agent base. */
+export function cursorAccountMcpPath(connectionName: string): string {
+  return `/v1/cursor-account/${connectionName}/mcp`;
+}
+
+/**
+ * Resolve account refs to engine connections once the server is listening.
+ * Local turns and host-side `ctx.host.mcp` reach the loopback bridge with
+ * the per-boot secret. When `publicUrl` is configured, cloud turns use the
+ * same bridge route so `servers` filters apply there too.
+ */
+export function resolveCursorAccountConnections(args: {
+  refs: CursorAccountConnectionRef[];
+  /** Serve bind URL (`http://<host>:<port>`). */
+  serverUrl: string;
+  basePath: string;
+  bridgeSecret: string;
+  publicUrl?: string;
+}): EngineResolvedConnection[] {
+  const serverBase = trimTrailingSlash(args.serverUrl);
+  const publicBase = args.publicUrl === undefined ? undefined : trimTrailingSlash(args.publicUrl);
+  const headers = { authorization: `Bearer ${args.bridgeSecret}` };
+  return args.refs.map(ref => ({
+    name: ref.name,
+    localUrl: `${serverBase}${args.basePath}${cursorAccountMcpPath(ref.name)}`,
+    ...(publicBase === undefined
+      ? {}
+      : {
+          cloudUrl: `${publicBase}${args.basePath}${cursorAccountMcpPath(ref.name)}`,
+        }),
+    headers,
+    ...(ref.servers === undefined ? {} : { accountServersFilter: ref.servers }),
+  }));
+}
+
+// ============================================================================
+// Bridge
+// ============================================================================
+
+interface CatalogTool {
+  /** Name exposed to MCP clients (sanitized, collision-free). */
+  exposedName: string;
+  /** Fully-qualified backend tool name (`<server>-<tool>`), the execution key. */
+  backendName: string;
+  serverIdentifier: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  /** Present only when the connector's server declares one. */
+  outputSchema?: Record<string, unknown>;
+  /** MCP spec annotations, present only when the server declared them. */
+  annotations?: McpToolAnnotations;
+}
+
+interface Catalog {
+  servers: AccountMcpServer[];
+  tools: CatalogTool[];
+  byExposedName: Map<string, CatalogTool>;
+}
+
+/**
+ * One in-flight-or-settled catalog fetch. In-flight entries omit
+ * {@link CatalogEntry.freshAtMs}; readers join {@link CatalogEntry.promise}
+ * synchronously so concurrent stale lookups converge on one refresh.
+ */
+interface CatalogEntry {
+  /** When the list call finished successfully; TTL counts from here. */
+  freshAtMs?: number;
+  promise: Promise<Catalog>;
+}
+
+export class CursorAccountMcpBridge {
+  /** Per-boot shared secret; resolved connections carry it as a bearer. */
+  readonly secret: string = randomBytes(32).toString("hex");
+  private readonly client: CursorBackendClient;
+  private readonly logger: (line: string) => void;
+  private readonly palette: TerminalPalette;
+  private readonly secretPolicy: AuthPolicy;
+  private readonly allowRemoteCallers: boolean;
+  private readonly catalogs = new Map<string, CatalogEntry>();
+
+  constructor(args: {
+    client: CursorBackendClient;
+    logger?: (line: string) => void;
+    /** Defaults to stdout; tests pass `makePalette(false)` for a plain box. */
+    palette?: TerminalPalette;
+    /**
+     * Admit non-loopback callers presenting the secret. Only set when the
+     * serve host configured a `publicUrl` (cloud turns reach the bridge
+     * through it); otherwise the bridge stays strictly loopback-only.
+     */
+    allowRemoteCallers?: boolean;
+  }) {
+    this.client = args.client;
+    this.logger = args.logger ?? (() => {});
+    this.palette = args.palette ?? stdoutPalette();
+    this.secretPolicy = bearerAuth(this.secret);
+    this.allowRemoteCallers = args.allowRemoteCallers === true;
+  }
+
+  /**
+   * Route auth for the bridge: the per-boot bearer secret, from a loopback
+   * TCP peer — or from anywhere when the serve host exposed the bridge via
+   * `publicUrl` (cloud turns arrive through that ingress with the secret).
+   */
+  authPolicy(): AuthPolicy {
+    return async (request, info) => {
+      const loopback = info.requestIp !== null && isLoopbackAddress(info.requestIp);
+      if (!loopback && !this.allowRemoteCallers) {
+        return null;
+      }
+      if ((await this.secretPolicy(request, info)) === null) {
+        return null;
+      }
+      return {
+        authenticator: "cursor-account-bridge",
+        principalId: "cursor-account-bridge",
+        principalType: "runtime",
+      };
+    };
+  }
+
+  /**
+   * Handle one streamable-HTTP MCP request for the connection described by
+   * `ref` (stateless: fresh server per POST, like the per-agent endpoint).
+   */
+  handle(
+    request: Request,
+    ref: CursorAccountConnectionRef,
+    decorate?: (sessionId: string, result: AccountMcpCallResult) => AccountMcpCallResult,
+  ): Promise<Response> {
+    const sessionId = new URL(request.url).searchParams.get("agentkitSessionId") ?? "";
+    return handleStatelessMcpRequest({
+      request,
+      buildServer: () => this.buildServer(ref, sessionId, decorate),
+      label: "cursor account bridge",
+      logger: this.logger,
+    });
+  }
+
+  /**
+   * Startup DX: log the account's connector statuses for `refs` without
+   * blocking serve startup. Healthy catalogs stay a one-line summary;
+   * `needsAuth` / `error` / empty catalogs render a yellow warning box with
+   * reconnect URLs.
+   *
+   * Returns a promise that settles when every ref's log lines are written —
+   * callers may ignore it; tests can await it.
+   */
+  async probeAuthUrl(ref: CursorAccountConnectionRef): Promise<string | undefined> {
+    const identifiers =
+      ref.servers !== undefined && ref.servers.length > 0
+        ? [...ref.servers]
+        : (await this.client.getAvailableMcpServers()).map(
+            server => server.serverIdentifier ?? server.name,
+          );
+    const urls = await probeConnectorAuthUrls({
+      client: this.client,
+      identifiers,
+    });
+    for (const url of urls.values()) {
+      if (url !== "") {
+        return url;
+      }
+    }
+    return undefined;
+  }
+
+  logPreflight(refs: CursorAccountConnectionRef[]): Promise<void> {
+    return Promise.all(refs.map(ref => this.runPreflight(ref))).then(() => undefined);
+  }
+
+  private async runPreflight(ref: CursorAccountConnectionRef): Promise<void> {
+    try {
+      const catalog = await this.getCatalog(ref);
+      const errorDetails = new Map<string, string>();
+      const needsAuthNames = catalog.servers
+        .filter(server => server.status === "needsAuth")
+        .map(server => server.serverIdentifier);
+      const [authUrls] = await Promise.all([
+        probeConnectorAuthUrls({
+          client: this.client,
+          identifiers: needsAuthNames,
+        }),
+        Promise.all(
+          catalog.servers
+            .filter(server => server.status === "error")
+            .map(async server => {
+              const detail = await diagnoseConnectorError(this.client, server.serverIdentifier);
+              if (detail !== undefined) {
+                errorDetails.set(server.serverIdentifier, detail);
+              }
+            }),
+        ),
+      ]);
+
+      const unhealthy = catalog.servers.some(
+        server => server.status === "needsAuth" || server.status === "error",
+      );
+      if (catalog.servers.length === 0 || unhealthy) {
+        this.logger(
+          formatCursorAccountMcpWarningBox({
+            connectionName: ref.name,
+            servers: catalog.servers.map(server => ({
+              serverIdentifier: server.serverIdentifier,
+              status: server.status,
+              toolCount: server.tools.length,
+              errorDetail: errorDetails.get(server.serverIdentifier),
+              authUrl: authUrls.get(server.serverIdentifier),
+            })),
+            palette: this.palette,
+          }),
+        );
+        return;
+      }
+
+      const summary = catalog.servers
+        .map(server => formatServerStatusSummary(server, errorDetails.get(server.serverIdentifier)))
+        .join(", ");
+      this.logger(`${LOG_PREFIX} Cursor account MCP connection "${ref.name}": ${summary}`);
+    } catch (error: unknown) {
+      this.logger(
+        `${LOG_PREFIX} Cursor account MCP connection "${ref.name}" preflight failed: ${describeError(error)}`,
+      );
+    }
+  }
+
+  private buildServer(
+    ref: CursorAccountConnectionRef,
+    sessionId: string,
+    decorate?: (sessionId: string, result: AccountMcpCallResult) => AccountMcpCallResult,
+  ): Server {
+    const server = new Server(
+      { name: `cursor-account:${ref.name}`, version: "0.1.0" },
+      {
+        capabilities: { tools: {} },
+        instructions:
+          "Tools from the Cursor account's MCP connectors. Every call executes on the Cursor backend with the account's stored credentials.",
+      },
+    );
+
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+      const catalog = await this.getCatalog(ref);
+      return {
+        tools: catalog.tools.map(tool => ({
+          name: tool.exposedName,
+          description: tool.description,
+          inputSchema: tool.inputSchema,
+          ...(tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema }),
+          // Already bounded to the MCP-spec fields at the backend-client
+          // parse; absent stays absent so classifiers fail closed.
+          ...(tool.annotations === undefined ? {} : { annotations: tool.annotations }),
+        })),
+      };
+    });
+
+    server.setRequestHandler(CallToolRequestSchema, async request => {
+      const tool = await this.findTool(ref, request.params.name);
+      if (tool === undefined) {
+        const catalog = await this.getCatalog(ref);
+        const unhealthy = catalog.servers.filter(server => server.status !== "connected");
+        const statusHint =
+          unhealthy.length === 0
+            ? ""
+            : ` Unhealthy connectors: ${unhealthy
+                .map(server => `${server.serverIdentifier}=${server.status}`)
+                .join(", ")}.`;
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Unknown tool "${request.params.name}". Available: ${
+                catalog.tools.map(t => t.exposedName).join(", ") || "(none)"
+              }.${statusHint}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+      try {
+        const executed = await this.client.executeAccountMcpTool({
+          serverIdentifier: tool.serverIdentifier,
+          toolName: tool.backendName,
+          args: request.params.arguments ?? {},
+        });
+        const decorated = decorate === undefined ? executed : decorate(sessionId, executed);
+        return {
+          content: decorated.content,
+          isError: decorated.isError === true ? true : undefined,
+          structuredContent: decorated.structuredContent,
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Account connector tool failed: ${describeError(error)}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    });
+
+    return server;
+  }
+
+  /** Resolve a tool by exposed name, refreshing once when it is unknown. */
+  private async findTool(
+    ref: CursorAccountConnectionRef,
+    exposedName: string,
+  ): Promise<CatalogTool | undefined> {
+    const catalog = await this.getCatalog(ref);
+    const hit = catalog.byExposedName.get(exposedName);
+    if (hit !== undefined) {
+      return hit;
+    }
+    const fresh = await this.getCatalog(ref, { forceRefresh: true });
+    return fresh.byExposedName.get(exposedName);
+  }
+
+  /**
+   * Fetch (or join) the catalog for `ref`'s server filter. Staleness and
+   * joining are decided synchronously: in-flight entries always join their
+   * promise; fresh entries use {@link CatalogEntry.freshAtMs} for TTL.
+   */
+  private getCatalog(
+    ref: CursorAccountConnectionRef,
+    options?: { forceRefresh?: boolean },
+  ): Promise<Catalog> {
+    const key = ref.servers === undefined ? "*" : [...ref.servers].sort().join("\n");
+    const entry = this.catalogs.get(key);
+    if (entry !== undefined) {
+      if (entry.freshAtMs === undefined) {
+        return entry.promise;
+      }
+      const age = Date.now() - entry.freshAtMs;
+      const maxAge =
+        options?.forceRefresh === true ? FORCE_REFRESH_MIN_INTERVAL_MS : CATALOG_TTL_MS;
+      if (age < maxAge) {
+        return entry.promise;
+      }
+    }
+    const fresh: CatalogEntry = {
+      promise: this.client
+        .listAccountMcpTools(ref.servers ?? [])
+        .then(servers => {
+          const catalog = buildCatalog(servers);
+          fresh.freshAtMs = Date.now();
+          return catalog;
+        })
+        .catch((error: unknown) => {
+          // Never cache a failure — but only evict our own entry, so a slow
+          // failing fetch cannot delete a newer, healthy refresh.
+          if (this.catalogs.get(key) === fresh) {
+            this.catalogs.delete(key);
+          }
+          throw error;
+        }),
+    };
+    this.catalogs.set(key, fresh);
+    return fresh.promise;
+  }
+}
+
+/**
+ * Build the exposed-tool catalog. Collision suffixes are assigned after
+ * sorting the colliding group by backend identity, so the exposed-name →
+ * backend-tool mapping is stable across refreshes even when the backend
+ * enumerates servers in a different order.
+ */
+function buildCatalog(servers: AccountMcpServer[]): Catalog {
+  const byBase = new Map<
+    string,
+    Array<{ serverIdentifier: string; tool: AccountMcpServer["tools"][number] }>
+  >();
+  for (const server of servers) {
+    for (const tool of server.tools) {
+      const base = sanitizeMcpToolName(tool.name);
+      const group = byBase.get(base);
+      const item = { serverIdentifier: server.serverIdentifier, tool };
+      if (group === undefined) {
+        byBase.set(base, [item]);
+      } else {
+        group.push(item);
+      }
+    }
+  }
+
+  const tools: CatalogTool[] = [];
+  const byExposedName = new Map<string, CatalogTool>();
+  // Process sanitize bases in deterministic order so cross-group exposed-name
+  // reservation does not depend on backend server listing order.
+  const sortedBases = [...byBase.keys()].sort((left, right) =>
+    left < right ? -1 : left > right ? 1 : 0,
+  );
+  for (const base of sortedBases) {
+    const group = byBase.get(base)!;
+    // Codepoint comparison (not localeCompare): the suffix assignment must
+    // be identical on every host and across refreshes.
+    group.sort((a, b) => {
+      const left = `${a.serverIdentifier}\n${a.tool.name}`;
+      const right = `${b.serverIdentifier}\n${b.tool.name}`;
+      return left < right ? -1 : left > right ? 1 : 0;
+    });
+    group.forEach(({ serverIdentifier, tool }, index) => {
+      let suffixIndex = index;
+      let exposedName = suffixMcpToolName(base, suffixIndex);
+      while (byExposedName.has(exposedName)) {
+        suffixIndex++;
+        exposedName = suffixMcpToolName(base, suffixIndex);
+      }
+      const entry: CatalogTool = {
+        exposedName,
+        backendName: tool.name,
+        serverIdentifier,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        ...(tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema }),
+        ...(tool.annotations === undefined ? {} : { annotations: tool.annotations }),
+      };
+      tools.push(entry);
+      byExposedName.set(entry.exposedName, entry);
+    });
+  }
+  return { servers, tools, byExposedName };
+}
+
+function trimTrailingSlash(url: string): string {
+  return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+
+export interface CursorAccountMcpWarningServer {
+  serverIdentifier: string;
+  status: string;
+  toolCount: number;
+  errorDetail?: string;
+  /** Minted OAuth URL for a `needsAuth` connector, when the probe succeeded. */
+  authUrl?: string;
+}
+
+const MAX_ERROR_DETAIL_CHARS = 72;
+
+function truncateDetail(detail: string): string {
+  const trimmed = detail.trim();
+  if (trimmed.length <= MAX_ERROR_DETAIL_CHARS) {
+    return trimmed;
+  }
+  return `${trimmed.slice(0, MAX_ERROR_DETAIL_CHARS - 1)}…`;
+}
+
+function formatWarningStatusRow(
+  server: CursorAccountMcpWarningServer,
+  nameWidth: number,
+  hyperlinks: boolean,
+): string {
+  const name = server.serverIdentifier.padEnd(nameWidth);
+  switch (server.status) {
+    case "needsAuth":
+      return `${name}  ${terminalHyperlink(connectUrl(server.authUrl), "Connect", hyperlinks)}`;
+    case "connected":
+      return `${name}  ${server.toolCount} tools`;
+    case "error": {
+      const detail =
+        server.errorDetail === undefined || server.errorDetail.trim() === ""
+          ? "backend could not reach connector"
+          : truncateDetail(server.errorDetail);
+      return `${name}  error: ${detail}`;
+    }
+    default:
+      return `${name}  ${server.status}`;
+  }
+}
+
+function connectUrl(authUrl: string | undefined): string {
+  const minted = authUrl?.trim() ?? "";
+  if (minted.startsWith("https://") && !minted.includes("\u001b") && !minted.includes("\u0007")) {
+    return minted;
+  }
+  return CURSOR_ACCOUNT_MCP_DASHBOARD_URL;
+}
+
+/**
+ * Yellow warning panel for unhealthy / missing Cursor-account connectors.
+ * One box replaces the old stacked `[agent-sdk]` log lines.
+ */
+export function formatCursorAccountMcpWarningBox(args: {
+  connectionName: string;
+  servers: readonly CursorAccountMcpWarningServer[];
+  palette?: TerminalPalette;
+  hyperlinks?: boolean;
+}): string {
+  const palette = args.palette ?? stdoutPalette();
+  const hyperlinks = args.hyperlinks ?? colorEnabledFor();
+  const copy = warningCopy({ ...args, hyperlinks });
+  return `\n${formatTerminalBox([copy.title, "", ...copy.intro, ...copy.actions], {
+    color: palette.yellow,
+    padding: 2,
+  })}`;
+}
+
+function warningCopy(args: {
+  connectionName: string;
+  servers: readonly CursorAccountMcpWarningServer[];
+  hyperlinks: boolean;
+}): { title: string; intro: string[]; actions: string[] } {
+  const empty = args.servers.length === 0;
+  const hasAuth = args.servers.some(server => server.status === "needsAuth");
+  const hasError = args.servers.some(server => server.status === "error");
+  const nameWidth = Math.max(0, ...args.servers.map(server => server.serverIdentifier.length));
+  const statusRows = args.servers.map(server =>
+    formatWarningStatusRow(server, nameWidth, args.hyperlinks),
+  );
+  const links = [
+    `  ${CURSOR_ACCOUNT_MCP_SETTINGS_DEEPLINK}`,
+    `  ${CURSOR_ACCOUNT_MCP_DASHBOARD_URL}`,
+  ];
+  const restart = "Then press Enter to restart this serve.";
+
+  if (empty) {
+    return {
+      title: "No matching MCP connectors",
+      intro: [`No matching connectors on this account ("${args.connectionName}").`],
+      actions: ["", "Connect servers in Cursor, or fix the `servers` filter.", ...links],
+    };
+  }
+  if (hasAuth && !hasError) {
+    return {
+      title: "MCP authorization needed",
+      intro: statusRows,
+      actions: ["", restart, "", "Or reconnect at:", ...links],
+    };
+  }
+  return {
+    title: hasAuth ? "MCP authorization needed" : "MCP connector error",
+    intro: statusRows,
+    actions: ["", "Re-check the server URL is healthy, then reconnect at:", ...links, "", restart],
+  };
+}
+
+/** One-line status for the preflight summary (`name (12 tools)` / `name (error: …)`). */
+export function formatServerStatusSummary(server: AccountMcpServer, errorDetail?: string): string {
+  switch (server.status) {
+    case "connected":
+      return `${server.serverIdentifier} (${server.tools.length} tools)`;
+    case "needsAuth":
+      return `${server.serverIdentifier} (needsAuth — re-authorize in Cursor)`;
+    case "loading":
+      return `${server.serverIdentifier} (loading)`;
+    case "error": {
+      const detail =
+        errorDetail === undefined || errorDetail.trim() === ""
+          ? "backend could not reach connector"
+          : errorDetail.trim();
+      return `${server.serverIdentifier} (error: ${detail})`;
+    }
+    default:
+      return `${server.serverIdentifier} (${server.status})`;
+  }
+}
+
+/**
+ * Best-effort detail for an `error`-status connector. ListSandMcpTools only
+ * returns the status enum today, so probe ExecuteSandMcpTool (ping) and surface
+ * the backend failure text (e.g. `HTTP MCP tool execution failed: fetch failed`).
+ */
+export async function diagnoseConnectorError(
+  client: Pick<CursorBackendClient, "executeAccountMcpTool">,
+  serverIdentifier: string,
+): Promise<string | undefined> {
+  try {
+    const result = await client.executeAccountMcpTool({
+      serverIdentifier,
+      // Conventional health tool; even a tool-not-found path usually still
+      // surfaces the same transport failure when the connector is down.
+      toolName: `${serverIdentifier}-ping`,
+      args: {},
+    });
+    const text = result.content
+      .filter((part): part is { type: "text"; text: string } => part.type === "text")
+      .map(part => part.text.trim())
+      .filter(part => part.length > 0)
+      .join(" ");
+    if (result.isError) {
+      return text.length > 0 ? text : "backend reported an error with no detail";
+    }
+    // Listing said error but ping succeeded — surface that inconsistency.
+    return text.length > 0
+      ? `listing reported error but probe succeeded: ${text}`
+      : "listing reported error but probe succeeded";
+  } catch (error: unknown) {
+    return describeError(error);
+  }
+}