@databrainhq/mcp-server 0.2.9 → 0.2.11

package/dist/index.js

@@ -8,9 +8,11 @@ import { z, ZodError } from "zod";
 var configSchema = z.object({
   serviceToken: z.string().min(1).optional(),
   apiToken: z.string().min(1).optional(),
-  apiUrl: z.string().url().default("https://api.usedatabrain.com")
-}).refine((c) => c.serviceToken || c.apiToken, {
-  message: "At least one of DATABRAIN_SERVICE_TOKEN or DATABRAIN_API_TOKEN must be set"
+  pat: z.string().min(1).optional(),
+  apiUrl: z.string().url().default("https://api.usedatabrain.com"),
+  demoDomain: z.string().url().default("https://demo.usedatabrain.com")
+}).refine((c) => c.serviceToken || c.apiToken || c.pat, {
+  message: "At least one of DATABRAIN_PAT, DATABRAIN_SERVICE_TOKEN, or DATABRAIN_API_TOKEN must be set"
 });
 function formatConfigError(err) {
   const issues = err.issues.map((i) => i.message);
@@ -19,8 +21,12 @@ function formatConfigError(err) {
     lines.push(`  - ${issue}`);
   }
   lines.push("");
-  lines.push("  Get a service token at Settings > Service Tokens in your Databrain dashboard.");
-  lines.push('  Then add to your MCP config: { "env": { "DATABRAIN_SERVICE_TOKEN": "..." } }');
+  lines.push("  Either:");
+  lines.push("    \u2022 Set DATABRAIN_PAT to a Personal Access Token (Settings > Personal Access Tokens) \u2014 preferred, binds this MCP session to your user.");
+  lines.push("    \u2022 OR set DATABRAIN_SERVICE_TOKEN (Settings > Service Tokens) \u2014 org-level, no per-user audit; the `connect` tool can mint a PAT on top.");
+  lines.push('  Then add to your MCP config: { "env": { "DATABRAIN_PAT": "..." } }');
+  lines.push("");
+  lines.push("  Self-hosted? Also set DATABRAIN_API_URL to your instance's API origin (e.g. https://api.your-databrain.example.com). Tokens minted on cloud do not work against a self-hosted instance and vice versa.");
   return lines.join("\n");
 }
 function loadConfig() {
@@ -28,7 +34,9 @@ function loadConfig() {
     return configSchema.parse({
       serviceToken: process.env.DATABRAIN_SERVICE_TOKEN || void 0,
       apiToken: process.env.DATABRAIN_API_TOKEN || void 0,
-      apiUrl: process.env.DATABRAIN_API_URL || "https://api.usedatabrain.com"
+      pat: process.env.DATABRAIN_PAT || void 0,
+      apiUrl: process.env.DATABRAIN_API_URL || "https://api.usedatabrain.com",
+      demoDomain: process.env.DATABRAIN_DEMO_DOMAIN || "https://demo.usedatabrain.com"
     });
   } catch (err) {
     if (err instanceof ZodError) {
@@ -78,13 +86,39 @@ var DatabrainApiError = class extends Error {
     this.name = "DatabrainApiError";
   }
   toToolResponse() {
+    const parts = [`Error: ${this.message}`];
+    const detailDump = this.formatDetails();
+    if (detailDump) parts.push(detailDump);
+    const hint = this.hint();
+    if (hint) parts.push(hint);
     return {
-      content: [{ type: "text", text: `Error: ${this.message}
-
-${this.hint()}` }],
+      content: [{ type: "text", text: parts.join("\n\n") }],
       isError: true
     };
   }
+  /**
+   * Surface API-returned details for 4xx errors so the LLM can recover or
+   * report the real reason (validation messages, field names, etc.). Skips
+   * fields already collapsed into `message`/`code`, and skips 5xx where the
+   * payload usually isn't actionable.
+   */
+  formatDetails() {
+    if (this.status < 400 || this.status >= 500) return "";
+    if (!this.details || typeof this.details !== "object") return "";
+    const skipKeys = /* @__PURE__ */ new Set(["message", "detail", "error", "code"]);
+    const extra = {};
+    for (const [k, v] of Object.entries(this.details)) {
+      if (skipKeys.has(k)) continue;
+      if (v === null || v === void 0) continue;
+      extra[k] = v;
+    }
+    if (Object.keys(extra).length === 0) return "";
+    try {
+      return `API details: ${JSON.stringify(extra)}`;
+    } catch {
+      return "";
+    }
+  }
   hint() {
     if (this.status === 401 || this.status === 403) {
       if (this.code === "INVALID_SERVICE_TOKEN" || this.code === "MISSING_SERVICE_TOKEN" || this.message.toLowerCase().includes("service token")) {
@@ -154,6 +188,122 @@ var logger = {
   error: (msg, data) => log("error", msg, data)
 };
 
+// src/auth/credential-store.ts
+import { mkdirSync, readFileSync, writeFileSync, renameSync, chmodSync, unlinkSync, existsSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+function defaultStorePath() {
+  const override = process.env.DATABRAIN_CREDENTIAL_PATH;
+  if (override) return override;
+  return join(homedir(), ".databrain", "mcp", "credentials.json");
+}
+function readStore(path) {
+  if (!existsSync(path)) return {};
+  try {
+    const raw = readFileSync(path, "utf8");
+    if (!raw.trim()) return {};
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+    return {};
+  } catch (err) {
+    logger.warn("Credential store unreadable, starting fresh", {
+      error: err.message
+    });
+    return {};
+  }
+}
+function writeStore(path, store) {
+  const dir = dirname(path);
+  mkdirSync(dir, { recursive: true, mode: 448 });
+  const tmp = `${path}.tmp.${process.pid}`;
+  writeFileSync(tmp, JSON.stringify(store, null, 2), { mode: 384 });
+  renameSync(tmp, path);
+  try {
+    chmodSync(path, 384);
+  } catch {
+  }
+}
+var CredentialStore = class {
+  constructor(path = defaultStorePath()) {
+    this.path = path;
+  }
+  get(baseUrl) {
+    const store = readStore(this.path);
+    const cred = store[normalizeUrl(baseUrl)];
+    return cred ?? null;
+  }
+  set(baseUrl, cred) {
+    const store = readStore(this.path);
+    store[normalizeUrl(baseUrl)] = cred;
+    writeStore(this.path, store);
+  }
+  clear(baseUrl) {
+    const store = readStore(this.path);
+    const key = normalizeUrl(baseUrl);
+    if (!(key in store)) return false;
+    delete store[key];
+    if (Object.keys(store).length === 0 && existsSync(this.path)) {
+      unlinkSync(this.path);
+    } else {
+      writeStore(this.path, store);
+    }
+    return true;
+  }
+  getPath() {
+    return this.path;
+  }
+};
+function normalizeUrl(url) {
+  return url.replace(/\/+$/, "");
+}
+
+// src/auth/operator.ts
+var OPERATOR_PAT_TTL_MS = 30 * 24 * 60 * 60 * 1e3;
+var storeSingleton;
+function getCredentialStore() {
+  if (!storeSingleton) storeSingleton = new CredentialStore();
+  return storeSingleton;
+}
+function loadCachedOperator(baseUrl) {
+  let cred;
+  try {
+    cred = getCredentialStore().get(baseUrl);
+  } catch (err) {
+    logger.warn("Credential store unreadable, treating as empty", {
+      error: err.message
+    });
+    return null;
+  }
+  if (!cred) return null;
+  if (cred.expiresAt && cred.expiresAt < Date.now()) return null;
+  return cred;
+}
+function persistOperator(baseUrl, response) {
+  const cred = {
+    pat: response.pat,
+    email: response.email,
+    userId: response.userId,
+    role: response.role,
+    workspaces: response.workspaces,
+    expiresAt: response.expiresAt
+  };
+  try {
+    getCredentialStore().set(baseUrl, cred);
+    return { cred, persisted: true };
+  } catch (err) {
+    logger.warn(
+      "Could not write operator credential to disk \u2014 using in-memory only for this session",
+      { error: err.message }
+    );
+    return { cred, persisted: false };
+  }
+}
+function clearOperator(baseUrl) {
+  return getCredentialStore().clear(baseUrl);
+}
+
 // src/client/databrain-client.ts
 var MCP_SERVER_VERSION = "0.2.0";
 var MCP_USER_AGENT = `databrain-mcp-server/${MCP_SERVER_VERSION}`;
@@ -175,6 +325,8 @@ var DatabrainClient = class {
   }
   cache = new TtlCache();
   runtimeApiToken;
+  operator = null;
+  operatorLoaded = false;
   hasApiToken() {
     return !!(this.runtimeApiToken || this.config.apiToken);
   }
@@ -188,12 +340,90 @@ var DatabrainClient = class {
   getApiUrl() {
     return this.config.apiUrl;
   }
+  getDemoDomain() {
+    return this.config.demoDomain;
+  }
+  getOperator() {
+    if (!this.operatorLoaded) {
+      this.operator = loadCachedOperator(this.config.apiUrl);
+      this.operatorLoaded = true;
+    }
+    return this.operator;
+  }
+  setOperator(cred) {
+    this.operator = cred;
+    this.operatorLoaded = true;
+    this.cache.invalidateByPrefix("");
+  }
+  clearOperator() {
+    this.operator = null;
+    this.operatorLoaded = true;
+    this.cache.invalidateByPrefix("");
+    return clearOperator(this.config.apiUrl);
+  }
+  async bootstrapOperator(email) {
+    if (!this.config.serviceToken) {
+      throw new DatabrainApiError(
+        401,
+        "MISSING_SERVICE_TOKEN",
+        "Cannot connect \u2014 DATABRAIN_SERVICE_TOKEN is not configured. Set it in your MCP server config first."
+      );
+    }
+    const response = await this.request({
+      method: "POST",
+      path: "/api/mcp/bootstrap",
+      body: { email },
+      auth: "service",
+      // Bootstrap uses the service token explicitly — not the operator PAT.
+      token: this.config.serviceToken
+    });
+    const result = persistOperator(this.config.apiUrl, response);
+    this.setOperator(result.cred);
+    return result;
+  }
+  /**
+   * Describes which credential is currently used as the bearer for outgoing
+   * API calls. Used by `whoami` so the LLM can give the user a truthful answer.
+   */
+  getActiveAuth() {
+    if (this.config.pat) return { source: "env-pat" };
+    const op = this.getOperator();
+    if (op?.pat) return { source: "cached-pat", operator: op };
+    if (this.config.serviceToken) return { source: "service-token" };
+    if (this.runtimeApiToken || this.config.apiToken) return { source: "api-token" };
+    return { source: "none" };
+  }
   getToken(auth) {
     if (auth === "none") return void 0;
+    if (this.config.pat) return this.config.pat;
+    const op = this.getOperator();
+    if (op?.pat) return op.pat;
     if (auth === "service") return this.config.serviceToken;
     return this.runtimeApiToken || this.config.apiToken;
   }
   async request(options) {
+    try {
+      return await this.requestInternal(options);
+    } catch (err) {
+      if (err instanceof DatabrainApiError && err.code === "PAT_EXPIRED" && !options.token && !this.config.pat && options.path !== "/api/mcp/bootstrap") {
+        const op = this.getOperator();
+        if (op?.email) {
+          logger.info("Operator PAT expired \u2014 silently re-bootstrapping");
+          try {
+            await this.bootstrapOperator(op.email);
+          } catch (bootstrapErr) {
+            logger.warn("Silent re-bootstrap failed", {
+              error: bootstrapErr.message
+            });
+            throw err;
+          }
+          return this.requestInternal(options);
+        }
+      }
+      throw err;
+    }
+  }
+  async requestInternal(options) {
     if (options.invalidateCache) {
       for (const prefix of options.invalidateCache) {
         this.cache.invalidateByPrefix(prefix);
@@ -479,6 +709,14 @@ var DatasourcesApi = class {
       cacheTtlMs: 5 * 60 * 1e3
     });
   }
+  async resolveIdByName(datasourceName) {
+    try {
+      const schema = await this.getDatasourceSchema(datasourceName);
+      return schema?.datasourceId || null;
+    } catch {
+      return null;
+    }
+  }
 };
 
 // src/api/embeds-api.ts
@@ -691,6 +929,7 @@ var DiscoveryService = class {
     return {
       name: isNonEmptyString(dashboard.name) && dashboard.name || isNonEmptyString(dashboard.dashboardName) && dashboard.dashboardName || "Unnamed Dashboard",
       dashboardId: isNonEmptyString(dashboard.dashboardId) && dashboard.dashboardId || isNonEmptyString(dashboard.externalDashboardId) && dashboard.externalDashboardId || isNonEmptyString(dashboard._id) && dashboard._id || isNonEmptyString(dashboard.id) && dashboard.id || isNonEmptyString(dashboard.uid) && dashboard.uid || null,
+      externalDashboardId: isNonEmptyString(dashboard.externalDashboardId) && dashboard.externalDashboardId || null,
       workspaceName: isNonEmptyString(dashboard.workspaceName) && dashboard.workspaceName || isNonEmptyString(dashboard.workspace) && dashboard.workspace || isNonEmptyString(dashboard.workspaceId) && dashboard.workspaceId || null,
       metricCount: typeof dashboard.metricCount === "number" ? dashboard.metricCount : null
     };
@@ -703,6 +942,7 @@ var DiscoveryService = class {
       embedId: isNonEmptyString(embed.embedId) ? embed.embedId : null,
       internalId: isNonEmptyString(embed._id) && embed._id || isNonEmptyString(embed.id) && embed.id || null,
       dashboardId: metadata && isNonEmptyString(metadata.dashboardId) && metadata.dashboardId || isNonEmptyString(embed.dashboardId) && embed.dashboardId || null,
+      externalDashboardId: isNonEmptyString(embed.externalDashboardId) && embed.externalDashboardId || externalDashboard && isNonEmptyString(externalDashboard.externalDashboardId) && externalDashboard.externalDashboardId || metadata && isNonEmptyString(metadata.externalDashboardId) && metadata.externalDashboardId || null,
       dataAppName: metadata && isNonEmptyString(metadata.dataAppName) && metadata.dataAppName || null,
       embedType: isNonEmptyString(embed.embedType) ? embed.embedType : null
     };
@@ -938,14 +1178,135 @@ var asRecord2 = (v) => {
 };
 var isActiveDatasource = (ds) => Boolean(ds.isAuthenticated) && !ds.isDisabled;
 var WidgetService = class {
-  constructor(widgetsApi, embedsApi, dataAppsApi, datasourcesApi, guestTokenService, discoveryService) {
+  constructor(widgetsApi, embedsApi, dataAppsApi, datasourcesApi, dashboardsApi, guestTokenService, discoveryService) {
     this.widgetsApi = widgetsApi;
     this.embedsApi = embedsApi;
     this.dataAppsApi = dataAppsApi;
     this.datasourcesApi = datasourcesApi;
+    this.dashboardsApi = dashboardsApi;
     this.guestTokenService = guestTokenService;
     this.discoveryService = discoveryService;
   }
+  /**
+   * Resolve the target embedId from a non-technical dashboard name (optionally
+   * scoped to a workspace). This is the preferred entry point for CS/CX flows
+   * where the user only knows the dashboard + workspace, not the embedId or
+   * data app name. Returns a business-user-friendly error on ambiguity.
+   */
+  async resolveEmbedFromDashboard(dashboardName, workspaceName) {
+    const wsProvided = workspaceName && workspaceName.trim().length > 0 ? workspaceName.trim() : void 0;
+    let dashboards;
+    try {
+      dashboards = wsProvided ? await this.dashboardsApi.listDashboardsForWorkspace(wsProvided) : await this.dashboardsApi.listDashboardsAcrossWorkspaces();
+    } catch (err) {
+      return {
+        ok: false,
+        error: `Could not list dashboards: ${err.message}`
+      };
+    }
+    const normalized = dashboards.map(
+      (d) => this.discoveryService.normalizeDashboard(d)
+    );
+    const target = dashboardName.trim().toLowerCase();
+    const matches = normalized.filter(
+      (d) => d.name.trim().toLowerCase() === target
+    );
+    if (matches.length === 0) {
+      const available = normalized.filter((d) => d.name && d.name !== "Unnamed Dashboard").map(
+        (d) => d.workspaceName ? `"${d.name}" (workspace: ${d.workspaceName})` : `"${d.name}"`
+      ).join(", ");
+      return {
+        ok: false,
+        error: `No dashboard named "${dashboardName}"${wsProvided ? ` in workspace "${wsProvided}"` : ""}. ` + (available ? `Available dashboards: ${available}. Ask the user to pick by dashboard name.` : "No dashboards exist in this organization.")
+      };
+    }
+    if (matches.length > 1) {
+      const workspaces = matches.map((d) => d.workspaceName || "(unknown workspace)").join(", ");
+      return {
+        ok: false,
+        error: `Dashboard name "${dashboardName}" is ambiguous \u2014 it exists in multiple workspaces (${workspaces}). Ask the user which workspace and retry with \`workspaceName\`.`
+      };
+    }
+    const dashboard = matches[0];
+    if (!dashboard.dashboardId) {
+      return {
+        ok: false,
+        error: `Dashboard "${dashboard.name}" has no ID. This is unexpected \u2014 ask the user to verify the dashboard in the Databrain UI.`
+      };
+    }
+    let embeds;
+    try {
+      embeds = await this.embedsApi.listEmbeds();
+    } catch (err) {
+      return {
+        ok: false,
+        error: `Could not list embeds: ${err.message}`
+      };
+    }
+    const dashboardIds = new Set(
+      [dashboard.dashboardId, dashboard.externalDashboardId].filter(
+        (v) => typeof v === "string" && v.length > 0
+      )
+    );
+    const embedMatches = embeds.map((e) => ({ raw: e, n: this.discoveryService.normalizeEmbed(e) })).filter((x) => {
+      if (!x.n.embedId) return false;
+      const embedIds = [x.n.dashboardId, x.n.externalDashboardId].filter(
+        (v) => typeof v === "string" && v.length > 0
+      );
+      return embedIds.some((id) => dashboardIds.has(id));
+    });
+    if (embedMatches.length === 0) {
+      return {
+        ok: false,
+        error: `Dashboard "${dashboard.name}" has no embed configured. An embed must be created in the Databrain UI before widgets can be managed for customers.`
+      };
+    }
+    if (embedMatches.length > 1) {
+      const names = embedMatches.map((x) => `"${x.n.name}"`).join(", ");
+      return {
+        ok: false,
+        error: `Dashboard "${dashboard.name}" has multiple embeds (${names}). Ask the user which embed name they want to customize.`
+      };
+    }
+    return {
+      ok: true,
+      value: {
+        embedId: embedMatches[0].n.embedId,
+        dashboardName: dashboard.name,
+        workspaceName: dashboard.workspaceName
+      }
+    };
+  }
+  /**
+   * Normalize widget-tool input: callers may supply `embedId` directly (legacy
+   * / technical callers) or `dashboardName` + optional `workspaceName`
+   * (non-technical CS/CX flow). Returns a single embedId and the resolved
+   * dashboard info if lookup happened. Pass `required: true` to enforce that
+   * the user named a target dashboard (recommended for CS/CX flows).
+   */
+  async resolveEmbedId(params) {
+    if (params.embedId && params.embedId.trim().length > 0) {
+      return { ok: true, value: { embedId: params.embedId.trim() } };
+    }
+    if (params.dashboardName && params.dashboardName.trim().length > 0) {
+      const res = await this.resolveEmbedFromDashboard(
+        params.dashboardName,
+        params.workspaceName
+      );
+      if (!res.ok) return res;
+      return {
+        ok: true,
+        value: { embedId: res.value.embedId, resolvedFrom: res.value }
+      };
+    }
+    if (params.required) {
+      return {
+        ok: false,
+        error: "Missing dashboard. Ask the user which dashboard to customize (by name) and optionally which workspace, then pass `dashboardName` (and `workspaceName` if needed). Technical callers may pass `embedId` directly."
+      };
+    }
+    return { ok: true, value: { embedId: null } };
+  }
   /**
    * Resolve the data app name from either a caller override, an embed's
    * metadata, or the sole data app in the workspace. Used by every widget
@@ -1014,8 +1375,8 @@ var WidgetService = class {
     );
     if (named.length === 1) {
       const ds = named[0];
-      const id = ds._id || ds.id || "";
       const name = ds.name;
+      const id = ds._id || ds.id || await this.datasourcesApi.resolveIdByName(name) || "";
       if (id && name) {
         return { ok: true, value: { integrationId: id, integrationName: name } };
       }
@@ -1030,14 +1391,17 @@ var WidgetService = class {
     let embedReason = "";
     if (params.embedId && embedProbe) {
       if (embedProbe.kind === "no_widgets") {
-        embedReason = ` Embed "${params.embedId}" has no widgets for clientId "${params.clientId}" to inherit from, so the datasource can't be auto-detected.`;
+        embedReason = ` This dashboard has no widgets for client "${params.clientId}" yet, so there's no existing widget to inherit the datasource from.`;
       } else if (embedProbe.kind === "no_metric_fields") {
-        embedReason = ` Checked ${embedProbe.widgetsTried} widget(s) on embed "${params.embedId}"` + (embedProbe.fetchErrors > 0 ? ` (${embedProbe.fetchErrors} could not be fetched)` : "") + `, but none had datasource metadata to inherit from.`;
+        embedReason = ` Checked ${embedProbe.widgetsTried} existing widget(s) on this dashboard` + (embedProbe.fetchErrors > 0 ? ` (${embedProbe.fetchErrors} could not be fetched)` : "") + `, but none had datasource metadata to inherit from.`;
       }
     }
     return {
       ok: false,
-      error: `Could not auto-resolve a datasource.${embedReason} Ask the user which datasource this widget should query \u2014 available options: ${nameList}. Then retry with \`integrationName: "<chosen name>"\` (no other fields needed). Technical callers can pass \`integrationId\` instead \u2014 see \`list_datasources\` for UUIDs.`
+      error: `Could not auto-detect the datasource for this dashboard.${embedReason} STOP and ASK the user to choose one of these two options:
+  (1) Pick an existing chart to copy from \u2014 call \`list_widgets\` and present the widgets by name, then retry via \`add_widget\` with \`templateMetricId\` (datasource inherited automatically). This is the recommended path for non-technical users.
+  (2) Pick a datasource by name from: ${nameList}. Retry with \`integrationName: "<chosen name>"\`. Only use this if the user already knows their datasource.
+Do not guess between the two \u2014 wait for the user to choose.`
     };
   }
   async completeFromDatasources(provided) {
@@ -1068,12 +1432,12 @@ var WidgetService = class {
       const hint = provided.integrationId ? `No active datasource matches integrationId "${provided.integrationId}". Available datasources: ${available || "(none)"}.` : `No active datasource matches integrationName "${provided.integrationName}". Available datasources: ${available || "(none)"}. Match is case-insensitive \u2014 double-check the name with the user.`;
       return { ok: false, error: hint };
     }
-    const id = target._id || target.id || "";
     const name = typeof target.name === "string" ? target.name : "";
+    const id = target._id || target.id || (name ? await this.datasourcesApi.resolveIdByName(name) : null) || "";
     if (!id || !name) {
       return {
         ok: false,
-        error: `Datasource match is missing id or name (id: "${id}", name: "${name}").`
+        error: `Could not resolve datasource "${name || provided.integrationName || provided.integrationId}" to a UUID. The datasource list API does not return IDs; the schema lookup also failed \u2014 the datasource may need to be synced in the Databrain UI.`
       };
     }
     return { ok: true, value: { integrationId: id, integrationName: name } };
@@ -1258,6 +1622,7 @@ function createServiceBundle(client) {
       embedsApi,
       dataAppsApi,
       datasourcesApi,
+      dashboardsApi,
       guestTokenService,
       discoveryService
     )
@@ -1658,9 +2023,7 @@ function registerListDatasources(server, client) {
         return toolSuccess(JSON.stringify({
           count: active.length,
           datasources: active.map((ds) => ({
-            id: ds._id || ds.id || null,
-            name: ds.name,
-            type: ds.dbName || ds.datasourceType || "unknown"
+            name: ds.name
           })),
           inactive: inactive.length > 0 ? inactive.map((ds) => ({ name: ds.name })) : void 0
         }));
@@ -1857,79 +2220,8 @@ function registerListWorkspaces(server, client) {
   );
 }
 
-// src/tools/infrastructure/link-datamart-to-workspace.ts
-import { z as z9 } from "zod";
-function registerLinkDatamartToWorkspace(server, client) {
-  server.tool(
-    "link_datamart_to_workspace",
-    "Link a datamart to an existing workspace. ALWAYS ask the user which workspace to use \u2014 do not auto-select.",
-    {
-      workspaceName: z9.string().optional().describe(
-        "Name of the workspace to update. Omit to list available workspaces and let the user choose."
-      ),
-      datamartName: z9.string().describe(
-        "Name of the datamart to link. Use `list_datamarts` to find it."
-      )
-    },
-    WRITE_IDEMPOTENT,
-    async ({ workspaceName, datamartName }) => {
-      try {
-        if (!workspaceName) {
-          const workspaces = await client.request({
-            method: "GET",
-            path: "/api/v2/workspace",
-            auth: "service",
-            cacheKey: "list_workspaces",
-            cacheTtlMs: 5 * 60 * 1e3
-          });
-          if (!Array.isArray(workspaces) || workspaces.length === 0) {
-            return toolError(
-              "No workspaces found. Create a workspace in the **Databrain UI** first, then come back here to link the datamart."
-            );
-          }
-          const list = workspaces.map((ws) => `- **${ws.name}** (ID: ${ws._id || ws.id})`).join("\n");
-          return toolSuccess(
-            `Found ${workspaces.length} workspace(s):
-
-${list}
-
-**Ask the user** which workspace they want to link to datamart **${datamartName}**, then call \`link_datamart_to_workspace\` with both \`workspaceName\` and \`datamartName\`.`
-          );
-        }
-        const result = await client.request({
-          method: "PUT",
-          path: "/api/v2/workspace",
-          body: {
-            name: workspaceName,
-            connectionType: "DATAMART",
-            datamartName
-          },
-          auth: "service",
-          invalidateCache: ["list_workspaces"]
-        });
-        if (result.error) {
-          return toolError(
-            `Failed to link datamart: ${typeof result.error === "object" ? JSON.stringify(result.error) : result.error}`
-          );
-        }
-        return toolSuccess(
-          `Workspace **${workspaceName}** is now linked to datamart **${datamartName}**.
-
-Next steps:
-- Build dashboards in the Databrain UI using this workspace
-- Use \`list_dashboards\` to find dashboards in this workspace
-- Use \`create_embed\` to embed dashboards into your app`
-        );
-      } catch (err) {
-        if (err instanceof DatabrainApiError) return err.toToolResponse();
-        return toolError(`Unexpected error: ${err.message}`);
-      }
-    }
-  );
-}
-
 // src/tools/embed/create-embed.ts
-import { z as z10 } from "zod";
+import { z as z9 } from "zod";
 var DEFAULT_ACCESS_SETTINGS2 = {
   isAllowMetricCreation: false,
   isAllowMetricDeletion: false,
@@ -1942,18 +2234,18 @@ var DEFAULT_ACCESS_SETTINGS2 = {
   isAllowCreateDashboardView: false,
   metricCreationMode: "DRAG_DROP"
 };
-var accessSettingsSchema = z10.object({
-  datamartName: z10.string().describe("Name of the datamart (required)"),
-  isAllowMetricCreation: z10.boolean().optional().describe("Allow end-users to create metrics"),
-  metricCreationMode: z10.enum(["DRAG_DROP", "CHAT"]).optional().describe("Metric creation mode"),
-  isAllowMetricDeletion: z10.boolean().optional().describe("Allow metric deletion"),
-  isAllowMetricUpdate: z10.boolean().optional().describe("Allow metric editing"),
-  isAllowMetricLayoutChange: z10.boolean().optional().describe("Allow layout changes"),
-  isAllowManageMetrics: z10.boolean().optional().describe("Show manage metrics UI"),
-  isAllowUnderlyingData: z10.boolean().optional().describe("Allow viewing underlying data"),
-  isAllowAiPilot: z10.boolean().optional().describe("Enable AI pilot features"),
-  isAllowEmailReports: z10.boolean().optional().describe("Allow email report scheduling"),
-  isAllowCreateDashboardView: z10.boolean().optional().describe("Allow creating dashboard views")
+var accessSettingsSchema = z9.object({
+  datamartName: z9.string().describe("Name of the datamart (required)"),
+  isAllowMetricCreation: z9.boolean().optional().describe("Allow end-users to create metrics"),
+  metricCreationMode: z9.enum(["DRAG_DROP", "CHAT"]).optional().describe("Metric creation mode"),
+  isAllowMetricDeletion: z9.boolean().optional().describe("Allow metric deletion"),
+  isAllowMetricUpdate: z9.boolean().optional().describe("Allow metric editing"),
+  isAllowMetricLayoutChange: z9.boolean().optional().describe("Allow layout changes"),
+  isAllowManageMetrics: z9.boolean().optional().describe("Show manage metrics UI"),
+  isAllowUnderlyingData: z9.boolean().optional().describe("Allow viewing underlying data"),
+  isAllowAiPilot: z9.boolean().optional().describe("Enable AI pilot features"),
+  isAllowEmailReports: z9.boolean().optional().describe("Allow email report scheduling"),
+  isAllowCreateDashboardView: z9.boolean().optional().describe("Allow creating dashboard views")
 }).describe("Embed access settings. Only datamartName is required \u2014 all flags default to false.");
 function registerCreateEmbed(server, client) {
   const services = createServiceBundle(client);
@@ -1961,23 +2253,23 @@ function registerCreateEmbed(server, client) {
     "create_embed",
     "Create an embed. Provide dashboardId, workspaceName, accessSettings.datamartName. Add clientId for multi-tenant per-client dashboards. All isAllow* flags default to false.",
     {
-      body: z10.record(z10.unknown()).optional().describe(
+      body: z9.record(z9.unknown()).optional().describe(
         "Raw API body passthrough. If provided, all other fields are ignored."
       ),
-      dashboardId: z10.string().optional().describe("Dashboard identifier for embed creation"),
-      workspaceName: z10.string().optional().describe("Workspace name. Omit to auto-resolve if only one exists."),
-      embedType: z10.enum(["dashboard", "metric"]).optional().describe("Embed type"),
-      metricId: z10.string().optional().describe("Required for metric embed type"),
-      name: z10.string().optional().describe("Human-readable embed config name"),
+      dashboardId: z9.string().optional().describe("Dashboard identifier for embed creation"),
+      workspaceName: z9.string().optional().describe("Workspace name. Omit to auto-resolve if only one exists."),
+      embedType: z9.enum(["dashboard", "metric"]).optional().describe("Embed type"),
+      metricId: z9.string().optional().describe("Required for metric embed type"),
+      name: z9.string().optional().describe("Human-readable embed config name"),
       accessSettings: accessSettingsSchema.optional(),
       // Multi-tenant (dashboard embed) params
-      clientId: z10.string().optional().describe(
+      clientId: z9.string().optional().describe(
         "Client identifier for multi-tenant isolation. When provided, creates a dashboard embed (each client gets their own dashboard copy)."
       ),
-      templateDashboardId: z10.string().optional().describe("Template dashboard ID to clone metrics from"),
-      isImportMetrics: z10.boolean().optional().describe("Import metrics from template dashboard"),
-      metricImportMode: z10.enum(["COPY", "LINK"]).optional().describe("COPY duplicates metrics, LINK shares them"),
-      isRenameDashboard: z10.boolean().optional().describe("Rename the dashboard for this client")
+      templateDashboardId: z9.string().optional().describe("Template dashboard ID to clone metrics from"),
+      isImportMetrics: z9.boolean().optional().describe("Import metrics from template dashboard"),
+      metricImportMode: z9.enum(["COPY", "LINK"]).optional().describe("COPY duplicates metrics, LINK shares them"),
+      isRenameDashboard: z9.boolean().optional().describe("Rename the dashboard for this client")
     },
     WRITE_CREATE,
     async (params) => {
@@ -2079,14 +2371,14 @@ Next: run \`get_embed_details\` to verify the embed configuration.`
 }
 
 // src/tools/embed/list-embeds.ts
-import { z as z11 } from "zod";
+import { z as z10 } from "zod";
 function registerListEmbeds(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "list_embeds",
-    "List embed configurations. Requires an API token (use create_api_token first).",
+    "List embed configurations. Requires an API token (use create_api_token first). Response includes `distinctClientIds` \u2014 a deduped list of end-customer client IDs that have multi-tenant dashboard embeds, useful for discovering which customers exist when only the workspace operator persona knows them.",
     {
-      dataAppName: z11.string().optional().describe("Filter by data app name")
+      dataAppName: z10.string().optional().describe("Filter by data app name")
     },
     READ_ONLY,
     async (params) => {
@@ -2097,19 +2389,28 @@ function registerListEmbeds(server, client) {
             "No embeds found. Create an embed in the Databrain UI, then run `list_embeds` again."
           );
         }
+        const embeds = result.map((e) => {
+          const n = services.discoveryService.normalizeEmbed(e);
+          const clientId = typeof e.clientId === "string" && e.clientId.trim().length > 0 ? e.clientId : null;
+          return {
+            embedId: n.embedId || null,
+            internalId: !n.embedId && n.internalId ? n.internalId : void 0,
+            name: n.name,
+            type: n.embedType || "dashboard",
+            dashboardId: n.dashboardId || null,
+            dataApp: n.dataAppName || null,
+            clientId
+          };
+        });
+        const distinctClientIds = Array.from(
+          new Set(
+            embeds.map((e) => e.clientId).filter((id) => typeof id === "string" && id.length > 0)
+          )
+        ).sort();
         return toolSuccess(JSON.stringify({
-          count: result.length,
-          embeds: result.map((e) => {
-            const n = services.discoveryService.normalizeEmbed(e);
-            return {
-              embedId: n.embedId || null,
-              internalId: !n.embedId && n.internalId ? n.internalId : void 0,
-              name: n.name,
-              type: n.embedType || "dashboard",
-              dashboardId: n.dashboardId || null,
-              dataApp: n.dataAppName || null
-            };
-          })
+          count: embeds.length,
+          distinctClientIds,
+          embeds
         }));
       } catch (err) {
         if (err instanceof DatabrainApiError) return err.toToolResponse();
@@ -2120,14 +2421,14 @@ function registerListEmbeds(server, client) {
 }
 
 // src/tools/embed/get-embed-details.ts
-import { z as z12 } from "zod";
+import { z as z11 } from "zod";
 function registerGetEmbedDetails(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "get_embed_details",
     "Get full embed configuration including access settings and theme.",
     {
-      embedId: z12.string().describe("ID of the embed")
+      embedId: z11.string().describe("ID of the embed")
     },
     READ_ONLY,
     async (params) => {
@@ -2143,7 +2444,7 @@ function registerGetEmbedDetails(server, client) {
 }
 
 // src/tools/embed/update-embed.ts
-import { z as z13 } from "zod";
+import { z as z12 } from "zod";
 
 // src/tools/embed/helpers.ts
 var GUEST_TOKEN_REMINDER = "\n\n\u26A0\uFE0F **Guest tokens must be regenerated** for these changes to take effect. Existing guest tokens still carry the old settings. Call `generate_guest_token` to create a new token with the updated configuration.";
@@ -2181,15 +2482,15 @@ function registerUpdateEmbed(server, client) {
     "update_embed",
     "Update embed access settings, permissions, theme, or name.",
     {
-      embedId: z13.string().describe("ID of the embed to update"),
-      body: z13.record(z13.unknown()).optional().describe(
+      embedId: z12.string().describe("ID of the embed to update"),
+      body: z12.record(z12.unknown()).optional().describe(
         "Raw API body for PUT /api/v2/data-app/embeds. If provided, it is sent directly (passthrough mode)."
       ),
-      name: z13.string().optional().describe("New name for the embed"),
-      accessSettings: z13.record(z13.unknown()).optional().describe(
+      name: z12.string().optional().describe("New name for the embed"),
+      accessSettings: z12.record(z12.unknown()).optional().describe(
         "Partial update of access settings. See `get_embed_details` for current settings."
       ),
-      theme: z13.record(z13.unknown()).optional().describe(
+      theme: z12.record(z12.unknown()).optional().describe(
         "Theme configuration object. See databrain://theme-reference for the full schema."
       )
     },
@@ -2235,7 +2536,7 @@ function registerUpdateEmbed(server, client) {
 }
 
 // src/tools/embed/customize-theme.ts
-import { z as z14 } from "zod";
+import { z as z13 } from "zod";
 var THEME_PRESETS = {
   light: {
     general: {
@@ -2369,7 +2670,7 @@ var ACCESS_PRESETS = {
     metricCreationMode: "CHAT"
   }
 };
-var fontFamilyEnum = z14.enum([
+var fontFamilyEnum = z13.enum([
   "Inter",
   "Roboto",
   "Open Sans",
@@ -2381,17 +2682,17 @@ var fontFamilyEnum = z14.enum([
   "Nunito",
   "system-ui"
 ]).describe("Font family");
-var tooltipFontSchema = z14.object({
-  fontFamily: z14.string().optional(),
-  fontSize: z14.number().optional(),
-  fontWeight: z14.number().optional(),
-  fontColor: z14.string().optional()
+var tooltipFontSchema = z13.object({
+  fontFamily: z13.string().optional(),
+  fontSize: z13.number().optional(),
+  fontWeight: z13.number().optional(),
+  fontColor: z13.string().optional()
 }).optional();
-var fontConfigInputSchema = z14.object({
-  fontSize: z14.number().optional(),
-  fontFamily: z14.string().optional(),
-  fontWeight: z14.number().optional(),
-  color: z14.string().optional()
+var fontConfigInputSchema = z13.object({
+  fontSize: z13.number().optional(),
+  fontFamily: z13.string().optional(),
+  fontWeight: z13.number().optional(),
+  color: z13.string().optional()
 }).optional();
 function mapToFrontendFontConfig(input) {
   if (!input) return void 0;
@@ -2402,23 +2703,23 @@ function mapToFrontendFontConfig(input) {
     ...input.color && { color: input.color }
   };
 }
-var axisSchema = z14.object({
-  hideAxisLines: z14.boolean().optional().describe("Hide axis lines"),
-  hideSplitLines: z14.boolean().optional().describe("Hide grid/split lines"),
-  hideAxisLabels: z14.boolean().optional().describe("Hide axis labels"),
-  hideAxisTicks: z14.boolean().optional().describe("Hide axis tick marks"),
-  axisName: z14.string().optional().describe("Axis title text"),
-  axisNameOffset: z14.number().optional().describe("Axis title offset from axis"),
-  axisLabelMargin: z14.number().optional().describe("Margin between axis labels and chart area in pixels"),
-  fontSize: z14.number().optional().describe("Axis label font size"),
-  fontFamily: z14.string().optional().describe("Axis label font family"),
-  fontWeight: z14.number().optional().describe("Axis label font weight"),
-  color: z14.string().optional().describe("Axis label color (hex)"),
-  axisColor: z14.string().optional().describe("Axis line color (hex)"),
-  axisNameFontConfig: z14.object({
-    fontFamily: z14.string().optional(),
-    fontSize: z14.number().optional(),
-    fontWeight: z14.number().optional()
+var axisSchema = z13.object({
+  hideAxisLines: z13.boolean().optional().describe("Hide axis lines"),
+  hideSplitLines: z13.boolean().optional().describe("Hide grid/split lines"),
+  hideAxisLabels: z13.boolean().optional().describe("Hide axis labels"),
+  hideAxisTicks: z13.boolean().optional().describe("Hide axis tick marks"),
+  axisName: z13.string().optional().describe("Axis title text"),
+  axisNameOffset: z13.number().optional().describe("Axis title offset from axis"),
+  axisLabelMargin: z13.number().optional().describe("Margin between axis labels and chart area in pixels"),
+  fontSize: z13.number().optional().describe("Axis label font size"),
+  fontFamily: z13.string().optional().describe("Axis label font family"),
+  fontWeight: z13.number().optional().describe("Axis label font weight"),
+  color: z13.string().optional().describe("Axis label color (hex)"),
+  axisColor: z13.string().optional().describe("Axis line color (hex)"),
+  axisNameFontConfig: z13.object({
+    fontFamily: z13.string().optional(),
+    fontSize: z13.number().optional(),
+    fontWeight: z13.number().optional()
   }).optional().describe("Axis title font configuration")
 }).optional();
 function buildAdminTheme(p, presetBase) {
@@ -2574,94 +2875,94 @@ function registerCustomizeTheme(server, client) {
     "customize_embed_theme",
     `Theme an embed: presets (${Object.keys(THEME_PRESETS).join("/")}), colors, fonts, cards, chart appearance, responsive layout, or access presets (${Object.keys(ACCESS_PRESETS).join("/")}).`,
     {
-      embedId: z14.string().describe("ID of the embed to theme"),
-      body: z14.record(z14.unknown()).optional().describe(
+      embedId: z13.string().describe("ID of the embed to theme"),
+      body: z13.record(z13.unknown()).optional().describe(
         "Raw API body for PUT /api/v2/data-app/embeds. If provided, sent directly and all convenience fields are ignored."
       ),
       // --- Presets ---
-      themePreset: z14.enum(["light", "dark", "corporate", "minimal"]).optional().describe("Apply a theme preset as the base. Granular params below override preset values."),
-      accessPreset: z14.enum(["view-only", "power-user", "export-only", "ai-enabled"]).optional().describe("Apply an access settings preset"),
+      themePreset: z13.enum(["light", "dark", "corporate", "minimal"]).optional().describe("Apply a theme preset as the base. Granular params below override preset values."),
+      accessPreset: z13.enum(["view-only", "power-user", "export-only", "ai-enabled"]).optional().describe("Apply an access settings preset"),
       // --- General ---
       fontFamily: fontFamilyEnum.optional().describe("Global font family"),
-      datePickerFormat: z14.string().optional().describe("Date picker display format"),
+      datePickerFormat: z13.string().optional().describe("Date picker display format"),
       // --- Colors ---
-      primaryColor: z14.string().optional().describe("Primary accent color (hex)"),
-      backgroundColor: z14.string().optional().describe("Overall background color (hex)"),
-      textColor: z14.string().optional().describe("Default text color (hex)"),
-      ctaColor: z14.string().optional().describe("Call-to-action button color (hex)"),
-      ctaTextColor: z14.string().optional().describe("CTA button text color (hex)"),
+      primaryColor: z13.string().optional().describe("Primary accent color (hex)"),
+      backgroundColor: z13.string().optional().describe("Overall background color (hex)"),
+      textColor: z13.string().optional().describe("Default text color (hex)"),
+      ctaColor: z13.string().optional().describe("Call-to-action button color (hex)"),
+      ctaTextColor: z13.string().optional().describe("CTA button text color (hex)"),
       // --- Dashboard ---
-      dashboardBackgroundColor: z14.string().optional().describe("Dashboard container background (hex)"),
-      selectBoxSize: z14.enum(["small", "medium", "large"]).optional().describe("Filter select box size"),
-      selectBoxVariant: z14.enum(["floating", "outlined", "standard"]).optional().describe("Filter select box style"),
-      selectBoxBorderRadius: z14.string().optional().describe('Select box border radius (e.g. "20px")'),
-      selectBoxTextColor: z14.string().optional().describe("Select box text color (hex)"),
-      metricCardColor: z14.string().optional().describe("Metric card background color (hex)"),
+      dashboardBackgroundColor: z13.string().optional().describe("Dashboard container background (hex)"),
+      selectBoxSize: z13.enum(["small", "medium", "large"]).optional().describe("Filter select box size"),
+      selectBoxVariant: z13.enum(["floating", "outlined", "standard"]).optional().describe("Filter select box style"),
+      selectBoxBorderRadius: z13.string().optional().describe('Select box border radius (e.g. "20px")'),
+      selectBoxTextColor: z13.string().optional().describe("Select box text color (hex)"),
+      metricCardColor: z13.string().optional().describe("Metric card background color (hex)"),
       // --- Card Title ---
-      cardTitleFontSize: z14.string().optional().describe('Card title font size (e.g. "16px")'),
-      cardTitleFontWeight: z14.string().optional().describe('Card title font weight (e.g. "600")'),
-      cardTitleColor: z14.string().optional().describe("Card title text color (hex)"),
+      cardTitleFontSize: z13.string().optional().describe('Card title font size (e.g. "16px")'),
+      cardTitleFontWeight: z13.string().optional().describe('Card title font weight (e.g. "600")'),
+      cardTitleColor: z13.string().optional().describe("Card title text color (hex)"),
       // --- Card Description ---
-      cardDescriptionFontSize: z14.string().optional().describe("Card description font size"),
-      cardDescriptionFontWeight: z14.string().optional().describe("Card description font weight"),
-      cardDescriptionColor: z14.string().optional().describe("Card description text color (hex)"),
+      cardDescriptionFontSize: z13.string().optional().describe("Card description font size"),
+      cardDescriptionFontWeight: z13.string().optional().describe("Card description font weight"),
+      cardDescriptionColor: z13.string().optional().describe("Card description text color (hex)"),
       // --- Card Customization ---
-      cardPadding: z14.string().optional().describe("Card internal padding"),
-      cardBorderRadius: z14.string().optional().describe("Card border radius"),
-      cardShadow: z14.string().optional().describe("Card box-shadow CSS value"),
-      disableShadowOnHover: z14.boolean().optional().describe("Disable shadow on card hover"),
-      disableCardStroke: z14.boolean().optional().describe("Remove card border stroke"),
-      cardStrokeColor: z14.string().optional().describe("Card border stroke color (hex)"),
+      cardPadding: z13.string().optional().describe("Card internal padding"),
+      cardBorderRadius: z13.string().optional().describe("Card border radius"),
+      cardShadow: z13.string().optional().describe("Card box-shadow CSS value"),
+      disableShadowOnHover: z13.boolean().optional().describe("Disable shadow on card hover"),
+      disableCardStroke: z13.boolean().optional().describe("Remove card border stroke"),
+      cardStrokeColor: z13.string().optional().describe("Card border stroke color (hex)"),
       // --- Chart Colors (admin theme level) ---
-      chartFontFamily: z14.string().optional().describe("Font family for chart text"),
-      chartFontColor: z14.string().optional().describe("Font color for chart text (hex)"),
-      chartColors: z14.array(z14.string()).optional().describe("Array of chart series colors (hex)"),
-      chartPaletteName: z14.string().optional().describe("Name for a custom palette"),
-      chartPaletteColors: z14.array(z14.string()).optional().describe("9 colors for a custom palette"),
+      chartFontFamily: z13.string().optional().describe("Font family for chart text"),
+      chartFontColor: z13.string().optional().describe("Font color for chart text (hex)"),
+      chartColors: z13.array(z13.string()).optional().describe("Array of chart series colors (hex)"),
+      chartPaletteName: z13.string().optional().describe("Name for a custom palette"),
+      chartPaletteColors: z13.array(z13.string()).optional().describe("9 colors for a custom palette"),
       // --- Chart Tooltip (admin theme level) ---
       tooltipHeader: tooltipFontSchema.describe("Tooltip header font config"),
       tooltipLabel: tooltipFontSchema.describe("Tooltip label font config"),
       tooltipValue: tooltipFontSchema.describe("Tooltip value font config"),
       // --- Component Theme ---
-      buttonPrimaryColor: z14.string().optional().describe("Primary button background (hex)"),
-      buttonPrimaryTextColor: z14.string().optional().describe("Primary button text (hex)"),
-      buttonSecondaryColor: z14.string().optional().describe("Secondary button background (hex)"),
-      buttonSecondaryTextColor: z14.string().optional().describe("Secondary button text (hex)"),
-      checkboxCheckedColor: z14.string().optional().describe("Checked checkbox color (hex)"),
-      checkboxUncheckedColor: z14.string().optional().describe("Unchecked checkbox color (hex)"),
-      switchEnabledColor: z14.string().optional().describe("Enabled switch color (hex)"),
-      switchDisabledColor: z14.string().optional().describe("Disabled switch color (hex)"),
-      breadcrumbFontFamily: z14.string().optional().describe("Drill breadcrumb font family"),
-      breadcrumbFontColor: z14.string().optional().describe("Drill breadcrumb font color (hex)"),
-      breadcrumbActiveColor: z14.string().optional().describe("Active breadcrumb color (hex)"),
-      filterBadgeColor: z14.string().optional().describe("Multi-select filter badge color (hex)"),
-      filterBadgeTextColor: z14.string().optional().describe("Filter badge text color (hex)"),
-      datePickerColor: z14.string().optional().describe("Date picker accent color (hex)"),
+      buttonPrimaryColor: z13.string().optional().describe("Primary button background (hex)"),
+      buttonPrimaryTextColor: z13.string().optional().describe("Primary button text (hex)"),
+      buttonSecondaryColor: z13.string().optional().describe("Secondary button background (hex)"),
+      buttonSecondaryTextColor: z13.string().optional().describe("Secondary button text (hex)"),
+      checkboxCheckedColor: z13.string().optional().describe("Checked checkbox color (hex)"),
+      checkboxUncheckedColor: z13.string().optional().describe("Unchecked checkbox color (hex)"),
+      switchEnabledColor: z13.string().optional().describe("Enabled switch color (hex)"),
+      switchDisabledColor: z13.string().optional().describe("Disabled switch color (hex)"),
+      breadcrumbFontFamily: z13.string().optional().describe("Drill breadcrumb font family"),
+      breadcrumbFontColor: z13.string().optional().describe("Drill breadcrumb font color (hex)"),
+      breadcrumbActiveColor: z13.string().optional().describe("Active breadcrumb color (hex)"),
+      filterBadgeColor: z13.string().optional().describe("Multi-select filter badge color (hex)"),
+      filterBadgeTextColor: z13.string().optional().describe("Filter badge text color (hex)"),
+      datePickerColor: z13.string().optional().describe("Date picker accent color (hex)"),
       // --- Responsive Breakpoints ---
-      breakpointXl: z14.number().optional().describe("XL breakpoint width in px"),
-      breakpointLg: z14.number().optional().describe("LG breakpoint width in px"),
-      breakpointMd: z14.number().optional().describe("MD breakpoint width in px"),
-      breakpointSm: z14.number().optional().describe("SM breakpoint width in px"),
-      breakpointXs: z14.number().optional().describe("XS breakpoint width in px"),
+      breakpointXl: z13.number().optional().describe("XL breakpoint width in px"),
+      breakpointLg: z13.number().optional().describe("LG breakpoint width in px"),
+      breakpointMd: z13.number().optional().describe("MD breakpoint width in px"),
+      breakpointSm: z13.number().optional().describe("SM breakpoint width in px"),
+      breakpointXs: z13.number().optional().describe("XS breakpoint width in px"),
       // --- Metric Layout Columns ---
-      layoutColsXl: z14.number().optional().describe("Grid columns at XL breakpoint"),
-      layoutColsLg: z14.number().optional().describe("Grid columns at LG breakpoint"),
-      layoutColsMd: z14.number().optional().describe("Grid columns at MD breakpoint"),
-      layoutColsSm: z14.number().optional().describe("Grid columns at SM breakpoint"),
-      layoutColsXs: z14.number().optional().describe("Grid columns at XS breakpoint"),
-      layoutColsXxs: z14.number().optional().describe("Grid columns at XXS breakpoint"),
+      layoutColsXl: z13.number().optional().describe("Grid columns at XL breakpoint"),
+      layoutColsLg: z13.number().optional().describe("Grid columns at LG breakpoint"),
+      layoutColsMd: z13.number().optional().describe("Grid columns at MD breakpoint"),
+      layoutColsSm: z13.number().optional().describe("Grid columns at SM breakpoint"),
+      layoutColsXs: z13.number().optional().describe("Grid columns at XS breakpoint"),
+      layoutColsXxs: z13.number().optional().describe("Grid columns at XXS breakpoint"),
       // --- Chart Appearance (detailed) ---
       tooltipHeaderStyle: fontConfigInputSchema.describe("Tooltip header: fontSize, fontFamily, fontWeight, color"),
       tooltipLabelStyle: fontConfigInputSchema.describe("Tooltip label: fontSize, fontFamily, fontWeight, color"),
       tooltipValueStyle: fontConfigInputSchema.describe("Tooltip value: fontSize, fontFamily, fontWeight, color"),
-      labelPosition: z14.enum(["hidden", "top", "left", "right", "bottom", "inside"]).optional().describe("Data label position on charts"),
-      radialLabelPosition: z14.enum(["outside", "inside"]).optional().describe("Label position for radial/pie charts"),
-      marginTop: z14.number().optional().describe("Chart top margin in pixels"),
-      marginLeft: z14.number().optional().describe("Chart left margin in pixels"),
-      marginRight: z14.number().optional().describe("Chart right margin in pixels"),
-      marginBottom: z14.number().optional().describe("Chart bottom margin in pixels"),
-      legendShow: z14.boolean().optional().describe("Show or hide chart legend"),
-      legendPosition: z14.enum([
+      labelPosition: z13.enum(["hidden", "top", "left", "right", "bottom", "inside"]).optional().describe("Data label position on charts"),
+      radialLabelPosition: z13.enum(["outside", "inside"]).optional().describe("Label position for radial/pie charts"),
+      marginTop: z13.number().optional().describe("Chart top margin in pixels"),
+      marginLeft: z13.number().optional().describe("Chart left margin in pixels"),
+      marginRight: z13.number().optional().describe("Chart right margin in pixels"),
+      marginBottom: z13.number().optional().describe("Chart bottom margin in pixels"),
+      legendShow: z13.boolean().optional().describe("Show or hide chart legend"),
+      legendPosition: z13.enum([
         "top-left",
         "top-center",
         "top-right",
@@ -2671,17 +2972,17 @@ function registerCustomizeTheme(server, client) {
         "bottom-center",
         "bottom-right"
       ]).optional().describe("Legend position"),
-      legendLayout: z14.enum(["horizontal", "vertical"]).optional().describe("Legend layout direction"),
-      legendShape: z14.enum(["circle", "rect", "roundRect", "triangle", "diamond", "arrow", "none"]).optional().describe("Legend icon shape"),
-      legendFontSize: z14.number().optional().describe("Legend font size"),
-      legendFontWeight: z14.number().optional().describe("Legend font weight"),
-      legendFontFamily: z14.string().optional().describe("Legend font family"),
-      legendColor: z14.string().optional().describe("Legend text color (hex)"),
-      legendTruncateLength: z14.number().optional().describe("Max characters before truncating legend"),
-      disableLegendScrolling: z14.boolean().optional().describe("Disable scrolling in legend"),
-      enableVariableLegendPosition: z14.boolean().optional().describe("Allow user to drag legend"),
-      legendTop: z14.number().optional().describe("Custom legend top offset"),
-      legendLeft: z14.number().optional().describe("Custom legend left offset"),
+      legendLayout: z13.enum(["horizontal", "vertical"]).optional().describe("Legend layout direction"),
+      legendShape: z13.enum(["circle", "rect", "roundRect", "triangle", "diamond", "arrow", "none"]).optional().describe("Legend icon shape"),
+      legendFontSize: z13.number().optional().describe("Legend font size"),
+      legendFontWeight: z13.number().optional().describe("Legend font weight"),
+      legendFontFamily: z13.string().optional().describe("Legend font family"),
+      legendColor: z13.string().optional().describe("Legend text color (hex)"),
+      legendTruncateLength: z13.number().optional().describe("Max characters before truncating legend"),
+      disableLegendScrolling: z13.boolean().optional().describe("Disable scrolling in legend"),
+      enableVariableLegendPosition: z13.boolean().optional().describe("Allow user to drag legend"),
+      legendTop: z13.number().optional().describe("Custom legend top offset"),
+      legendLeft: z13.number().optional().describe("Custom legend left offset"),
       verticalAxis: axisSchema.describe("Vertical (Y) axis configuration"),
       horizontalAxis: axisSchema.describe("Horizontal (X) axis configuration")
     },
@@ -2755,6 +3056,76 @@ Use \`get_embed_details\` to view the full current theme configuration.` + GUEST
   );
 }
 
+// src/tools/embed/get-demo-link.ts
+import { z as z14 } from "zod";
+var HOUR_MS = 60 * 60 * 1e3;
+var DEFAULT_EXPIRY_HOURS = 24;
+var MAX_EXPIRY_HOURS = 24 * 30;
+function registerGetDemoLink(server, client) {
+  const services = createServiceBundle(client);
+  server.tool(
+    "get_demo_link",
+    `Get a shareable demo URL for a dashboard embed scoped to a specific clientId \u2014 same link the UI's "Share Demo Link" generates. Loads the dashboard as that end-customer sees it. Use to verify ops-built widgets without a test app.`,
+    {
+      clientId: z14.string().describe("End-customer identifier to scope the preview to."),
+      dashboardName: z14.string().optional().describe("Dashboard name (non-technical). Preferred \u2014 pass with optional `workspaceName`."),
+      workspaceName: z14.string().optional().describe("Workspace name. Only needed if `dashboardName` is ambiguous."),
+      embedId: z14.string().optional().describe("Technical alternative to `dashboardName`."),
+      expiryHours: z14.number().min(1).max(MAX_EXPIRY_HOURS).optional().describe(`Token TTL in hours. Defaults to ${DEFAULT_EXPIRY_HOURS}. Max ${MAX_EXPIRY_HOURS} (30 days).`)
+    },
+    READ_ONLY,
+    async (params) => {
+      try {
+        const embed = await services.widgetService.resolveEmbedId({
+          embedId: params.embedId,
+          dashboardName: params.dashboardName,
+          workspaceName: params.workspaceName,
+          required: true
+        });
+        if (!embed.ok) return toolError(embed.error);
+        const embedId = embed.value.embedId;
+        const dashboardName = embed.value.resolvedFrom?.dashboardName || null;
+        const ctx = await services.widgetService.resolveEmbedContext(embedId);
+        if (!ctx.dataAppName) {
+          return toolError(
+            `Could not resolve the data app for embed "${embedId}". The demo link needs a data app to mint a guest token against. Run \`list_data_apps\` to confirm one exists, or pass \`embedId\` for an embed with metadata.dataAppName populated.`
+          );
+        }
+        const dashboardSlug = ctx.externalDashboardId || ctx.dashboardId;
+        if (!dashboardSlug) {
+          return toolError(
+            `Embed "${embedId}" has no dashboardId/externalDashboardId \u2014 the demo URL requires one to load the dashboard. This is unexpected; verify the embed in the Databrain UI.`
+          );
+        }
+        const expiryHours = params.expiryHours ?? DEFAULT_EXPIRY_HOURS;
+        const { token } = await services.guestTokenService.generateToken({
+          clientId: params.clientId,
+          dataAppName: ctx.dataAppName,
+          allowedEmbeds: [embedId],
+          expiryTime: expiryHours * HOUR_MS
+        });
+        const baseUrl = client.getDemoDomain().replace(/\/+$/, "");
+        const demoUrl = `${baseUrl}/?token=${encodeURIComponent(token)}&dashboardId=${encodeURIComponent(dashboardSlug)}`;
+        return toolSuccess(
+          JSON.stringify({
+            demoUrl,
+            clientId: params.clientId,
+            dashboardName,
+            embedId,
+            dashboardId: dashboardSlug,
+            dataAppName: ctx.dataAppName,
+            expiresInHours: expiryHours,
+            note: `Open this URL in a browser to preview the dashboard exactly as the end-customer sees it. This matches the UI's "Share Demo Link" flow. Override the host with DATABRAIN_DEMO_DOMAIN for self-hosted / custom preview domains.`
+          })
+        );
+      } catch (err) {
+        if (err instanceof DatabrainApiError) return err.toToolResponse();
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
 // src/tools/frontend/generate-guest-token.ts
 import { z as z15 } from "zod";
 function registerGenerateGuestToken(server, client) {
@@ -4396,29 +4767,41 @@ function registerListWidgets(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "list_widgets",
-    "List widgets (metrics) on a customer dashboard embed. Returns each widget's metricId, name, published state, and creator identifier.",
+    "List widgets on a customer dashboard. Non-technical flow: pass `clientId` + `dashboardName` (+ optional `workspaceName` if ambiguous). Returns each widget's externalMetricId (uuid, used for update/remove), metricId (slug), name, published state, and creator identifier.",
     {
-      embedId: z21.string().describe("Embed ID (customer dashboard instantiation)"),
-      clientId: z21.string().describe("Client/tenant identifier for this embed")
+      clientId: z21.string().describe("Client/tenant identifier for this dashboard"),
+      dashboardName: z21.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z21.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z21.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier.")
     },
     READ_ONLY,
     async (params) => {
       try {
+        const embed = await services.widgetService.resolveEmbedId({
+          embedId: params.embedId,
+          dashboardName: params.dashboardName,
+          workspaceName: params.workspaceName,
+          required: true
+        });
+        if (!embed.ok) return toolError(embed.error);
+        const embedId = embed.value.embedId;
         const widgets = await services.widgetsApi.listWidgets(
-          params.embedId,
+          embedId,
           params.clientId
         );
         if (!Array.isArray(widgets) || widgets.length === 0) {
           return toolSuccess(
-            `No widgets found on embed "${params.embedId}" for client "${params.clientId}".`
+            `No widgets found on dashboard "${embed.value.resolvedFrom?.dashboardName || embedId}" for client "${params.clientId}".`
           );
         }
         return toolSuccess(
           JSON.stringify({
             count: widgets.length,
-            embedId: params.embedId,
+            dashboardName: embed.value.resolvedFrom?.dashboardName || null,
+            embedId,
             clientId: params.clientId,
             widgets: widgets.map((w) => ({
+              externalMetricId: typeof w.externalMetricId === "string" && w.externalMetricId || typeof w.id === "string" && w.id || typeof w._id === "string" && w._id || null,
               metricId: w.metricId || null,
               name: w.name || null,
               isPublished: w.isPublished ?? null,
@@ -4440,11 +4823,13 @@ function registerAddWidget(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "add_widget",
-    "Add a widget (metric) to a customer dashboard embed. Either clone via `templateMetricId` (recommended \u2014 inherits query, chartOptions, datasource), or supply a full spec (name + query + chartOptions). Datasource auto-resolves from the embed or sole active datasource; pass `integrationName` to override. Mints a guest token internally.",
+    "Add a widget to a customer dashboard. Non-technical flow: pass `clientId` + `dashboardName` (+ optional `workspaceName` if ambiguous). Cloning via `templateMetricId` is the recommended path \u2014 query, chart config, and datasource are all inherited. Data app and datasource auto-resolve; never ask the user for them.",
     {
-      embedId: z22.string().describe("Embed ID the widget will be added to"),
       clientId: z22.string().describe("Client/tenant identifier (widget is created in their scope)"),
-      dataAppName: z22.string().optional().describe("Data app name (required for guest token). Auto-resolved from embedId if omitted."),
+      dashboardName: z22.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z22.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z22.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
+      dataAppName: z22.string().optional().describe("Technical override. Auto-resolved from the embed; non-technical callers should leave this blank."),
       templateMetricId: z22.string().optional().describe("Source widget metricId to clone from. Copies query, chartOptions, and datasource fields; caller can override via other params."),
       name: z22.string().optional().describe("Widget name (overrides template)"),
       metricId: z22.string().optional().describe("Unique slug for the new widget (auto-generated if omitted)"),
@@ -4459,21 +4844,29 @@ function registerAddWidget(server, client) {
     WRITE_CREATE,
     async (params) => {
       try {
-        const ctx = await services.widgetService.resolveEmbedContext(params.embedId);
+        const embed = await services.widgetService.resolveEmbedId({
+          embedId: params.embedId,
+          dashboardName: params.dashboardName,
+          workspaceName: params.workspaceName,
+          required: true
+        });
+        if (!embed.ok) return toolError(embed.error);
+        const embedId = embed.value.embedId;
+        const ctx = await services.widgetService.resolveEmbedContext(embedId);
         if (!ctx.externalDashboardId) {
           return toolError(
-            `Embed "${params.embedId}" has no externalDashboardId \u2014 cannot attach a widget. Verify via \`get_embed_details\`.`
+            `Dashboard "${params.dashboardName || embedId}" has no externalDashboardId \u2014 cannot attach a widget. Verify via \`get_embed_details\`.`
           );
         }
         const dataAppName = await services.widgetService.resolveDataAppName(
           params.dataAppName,
-          params.embedId
+          embedId
         );
         if (!dataAppName.ok) return toolError(dataAppName.error);
         const guestToken = await services.widgetService.mintGuestToken(
           params.clientId,
           dataAppName.value,
-          [params.embedId]
+          [embedId]
         );
         let createBody;
         if (params.body) {
@@ -4505,7 +4898,7 @@ function registerAddWidget(server, client) {
           if (!params.name) return toolError("`name` is required when not cloning a template.");
           if (!params.query) return toolError("`query` is required when not cloning a template.");
           const datasource = await services.widgetService.resolveDatasource(guestToken, {
-            embedId: params.embedId,
+            embedId,
             clientId: params.clientId,
             integrationId: params.companyIntegrationId,
             integrationName: params.integrationName
@@ -4542,7 +4935,7 @@ ${JSON.stringify(createBody, null, 2).slice(0, 3e3)}`
 - externalMetricId: \`${newId}\`
 - metricId: \`${newMetricId}\`
 - name: \`${createBody.name}\`
-- embedId: \`${params.embedId}\`
+- dashboard: \`${embed.value.resolvedFrom?.dashboardName || embedId}\`
 - clientId: \`${params.clientId}\`
 
 Use \`list_widgets\` to verify, or \`update_widget\`/\`remove_widget\` to adjust.`
@@ -4561,12 +4954,14 @@ function registerUpdateWidget(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "update_widget",
-    "Update a widget on a customer dashboard embed. Applies a partial patch to the externalMetrics row (name, query, chartOptions, isPublished, etc.). Mints a guest token internally.",
+    "Update a widget on a customer dashboard. Non-technical flow: pass `clientId` + `dashboardName` (+ optional `workspaceName` if ambiguous) + `externalMetricId` + `set`. Data app auto-resolves from the dashboard.",
     {
       externalMetricId: z23.string().describe("Internal uuid of the widget (externalMetrics.id). Not the user-facing metricId slug."),
       clientId: z23.string().describe("Client/tenant identifier"),
-      dataAppName: z23.string().optional().describe("Optional override. Auto-resolved from `embedId`, or from the sole data app when there is only one."),
-      embedId: z23.string().optional().describe("Optional \u2014 if provided, the guest token is scoped to just this embed and dataAppName is auto-resolved."),
+      dashboardName: z23.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z23.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z23.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
+      dataAppName: z23.string().optional().describe("Technical override. Auto-resolved from the dashboard; non-technical callers should leave this blank."),
       set: z23.record(z23.unknown()).describe("Partial patch. Keys can include: name, query, chartOptions, description, isPublished, isLive, selectedGroupBy, drillDownSettings, limit, etc.")
     },
     WRITE_IDEMPOTENT,
@@ -4575,15 +4970,22 @@ function registerUpdateWidget(server, client) {
         if (!params.set || Object.keys(params.set).length === 0) {
           return toolError("`set` must contain at least one field to update.");
         }
+        const embed = await services.widgetService.resolveEmbedId({
+          embedId: params.embedId,
+          dashboardName: params.dashboardName,
+          workspaceName: params.workspaceName
+        });
+        if (!embed.ok) return toolError(embed.error);
+        const embedId = embed.value.embedId;
         const dataAppName = await services.widgetService.resolveDataAppName(
           params.dataAppName,
-          params.embedId
+          embedId || void 0
         );
         if (!dataAppName.ok) return toolError(dataAppName.error);
         const guestToken = await services.widgetService.mintGuestToken(
           params.clientId,
           dataAppName.value,
-          params.embedId ? [params.embedId] : void 0
+          embedId ? [embedId] : void 0
         );
         const result = await services.widgetsApi.updateMetric(guestToken, {
           externalMetricId: params.externalMetricId,
@@ -4620,25 +5022,34 @@ function registerRemoveWidget(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "remove_widget",
-    "Remove a widget from a customer dashboard embed. This is a per-client soft delete (writes to clientDeletedMetrics) \u2014 the widget stays on the template dashboard and on other customers' embeds.",
+    "Remove a widget from a customer dashboard. Non-technical flow: pass `clientId` + `dashboardName` (+ optional `workspaceName` if ambiguous) + `externalMetricId`. Per-client soft delete \u2014 the widget stays on the template dashboard and on other customers' dashboards.",
     {
       externalMetricId: z24.string().describe("Internal uuid of the widget (externalMetrics.id)"),
       clientId: z24.string().describe("Client/tenant identifier \u2014 the widget will be hidden for this client only"),
-      dataAppName: z24.string().optional().describe("Optional override. Auto-resolved from `embedId`, or from the sole data app when there is only one."),
-      embedId: z24.string().optional().describe("Optional \u2014 scopes the guest token to this embed and auto-resolves dataAppName.")
+      dashboardName: z24.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z24.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z24.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
+      dataAppName: z24.string().optional().describe("Technical override. Auto-resolved from the dashboard; non-technical callers should leave this blank.")
     },
     DESTRUCTIVE,
     async (params) => {
       try {
+        const embed = await services.widgetService.resolveEmbedId({
+          embedId: params.embedId,
+          dashboardName: params.dashboardName,
+          workspaceName: params.workspaceName
+        });
+        if (!embed.ok) return toolError(embed.error);
+        const embedId = embed.value.embedId;
         const dataAppName = await services.widgetService.resolveDataAppName(
           params.dataAppName,
-          params.embedId
+          embedId || void 0
         );
         if (!dataAppName.ok) return toolError(dataAppName.error);
         const guestToken = await services.widgetService.mintGuestToken(
           params.clientId,
           dataAppName.value,
-          params.embedId ? [params.embedId] : void 0
+          embedId ? [embedId] : void 0
         );
         const result = await services.widgetsApi.markArchived(guestToken, {
           id: params.externalMetricId,
@@ -4671,30 +5082,40 @@ function registerGenerateWidget(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "generate_widget",
-    "AI-generate a widget draft from a natural-language prompt. Does NOT persist \u2014 returns a draft to review and pass to `add_widget`. Data app and datasource auto-resolve from `embedId` (preferred) or sole workspace defaults. On resolve failure, ask the user for the datasource by name and pass `integrationName`.",
+    "AI-generate a widget draft from a natural-language prompt. Does NOT persist \u2014 returns a draft to pass to `add_widget`. Non-technical flow: `clientId` + `dashboardName` (+ `workspaceName` if ambiguous); data app and datasource auto-resolve. Never ask the user for data app, datasource, or integration.",
     {
       clientId: z25.string().describe("Client/tenant identifier"),
       userInputs: z25.record(z25.unknown()).describe('Prompt + context object. Typical shape: { prompt: "calls per day over last 30 days", schema: {...}, examples: [...] }. Backend decides which keys it honors.'),
-      embedId: z25.string().optional().describe("Optional. When provided, data app and datasource are inherited from the embed's existing widgets \u2014 the preferred path for CS/CX flows."),
-      dataAppName: z25.string().optional().describe("Optional override. Auto-resolved from embedId, or from the sole data app when there is only one."),
-      integrationId: z25.string().optional().describe("Technical override \u2014 the datasource UUID. Most flows should leave this blank and rely on auto-resolution from `embedId`. If you must override, prefer `integrationName` (business-user friendly)."),
-      integrationName: z25.string().optional().describe('Datasource display name (e.g. "Snowflake", "demo datasource"). Use this when the user picks a datasource by name \u2014 the id is looked up automatically. Leave blank if `embedId` is provided (auto-resolved).')
+      dashboardName: z25.string().optional().describe("Dashboard name (non-technical). Preferred input for CS/CX flows \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z25.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z25.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
+      dataAppName: z25.string().optional().describe("Technical override. Auto-resolved from the embed; non-technical callers should leave this blank."),
+      integrationId: z25.string().optional().describe("Technical override \u2014 the datasource UUID. Non-technical callers must leave this blank; the datasource is inherited from the dashboard's existing widgets."),
+      integrationName: z25.string().optional().describe("Technical override \u2014 datasource display name. Non-technical callers must leave this blank; the datasource is inherited from the dashboard's existing widgets.")
     },
     READ_ONLY,
     async (params) => {
       try {
+        const embed = await services.widgetService.resolveEmbedId({
+          embedId: params.embedId,
+          dashboardName: params.dashboardName,
+          workspaceName: params.workspaceName,
+          required: true
+        });
+        if (!embed.ok) return toolError(embed.error);
+        const embedId = embed.value.embedId;
         const dataAppName = await services.widgetService.resolveDataAppName(
           params.dataAppName,
-          params.embedId
+          embedId
         );
         if (!dataAppName.ok) return toolError(dataAppName.error);
         const guestToken = await services.widgetService.mintGuestToken(
           params.clientId,
           dataAppName.value,
-          params.embedId ? [params.embedId] : void 0
+          [embedId]
         );
         const datasource = await services.widgetService.resolveDatasource(guestToken, {
-          embedId: params.embedId,
+          embedId,
           clientId: params.clientId,
           integrationId: params.integrationId,
           integrationName: params.integrationName
@@ -4735,13 +5156,173 @@ function registerGenerateWidget(server, client) {
   );
 }
 
+// src/tools/auth/connect.ts
+import { z as z26 } from "zod";
+function registerConnect(server, client) {
+  server.tool(
+    "connect",
+    "Bind this MCP session to a Databrain user. Pass the user's Databrain login email; the server mints a personal token cached locally so subsequent actions are role-checked and audited under that user. One-time per machine.",
+    {
+      email: z26.string().email().describe("The Databrain login email for the user running this MCP session.")
+    },
+    WRITE_IDEMPOTENT,
+    async ({ email }) => {
+      try {
+        const { cred, persisted } = await client.bootstrapOperator(email);
+        const expiresInDays = Math.max(
+          0,
+          Math.round((cred.expiresAt - Date.now()) / (24 * 60 * 60 * 1e3))
+        );
+        const envPatActive = client.getActiveAuth().source === "env-pat";
+        const notes = [];
+        if (envPatActive) {
+          notes.push(
+            "DATABRAIN_PAT is set in your MCP env, so that token continues to be used as the bearer for API calls. The cached identity is now available for `whoami`. Unset DATABRAIN_PAT if you want this freshly minted PAT to be used instead."
+          );
+        } else {
+          notes.push(
+            "Mutations from this MCP session are now role-checked and audit-logged under this user."
+          );
+        }
+        if (!persisted) {
+          notes.push(
+            "Could not persist the credential to disk \u2014 likely a sandboxed or read-only home directory. The PAT is held in memory for this session only; you'll be asked to connect again next time the MCP server restarts. To avoid this, generate a PAT in Databrain Settings and paste it into your MCP config as DATABRAIN_PAT."
+          );
+        }
+        return toolSuccess(
+          JSON.stringify(
+            {
+              status: "connected",
+              email: cred.email,
+              userId: cred.userId,
+              role: cred.role,
+              workspaces: cred.workspaces,
+              expiresInDays,
+              persisted,
+              activeBearer: envPatActive ? "env-pat" : "cached-pat",
+              notes
+            },
+            null,
+            2
+          )
+        );
+      } catch (err) {
+        if (err instanceof DatabrainApiError) return err.toToolResponse();
+        return toolError(`Unexpected error during connect: ${err.message}`);
+      }
+    }
+  );
+}
+
+// src/tools/auth/whoami.ts
+function registerWhoami(server, client) {
+  server.tool(
+    "whoami",
+    "Return the credential currently used for API calls and (if known) the Databrain user it belongs to. Use to confirm operator identity before mutating actions.",
+    {},
+    READ_ONLY,
+    async () => {
+      const auth = client.getActiveAuth();
+      const cached = client.getOperator();
+      if (auth.source === "env-pat") {
+        const body = {
+          status: "connected",
+          activeBearer: "env-pat",
+          note: "Using DATABRAIN_PAT from your MCP env. The backend resolves the user behind this PAT \u2014 actions are role-checked and audited under their account."
+        };
+        if (cached) {
+          body.cachedIdentity = {
+            email: cached.email,
+            userId: cached.userId,
+            role: cached.role,
+            workspaces: cached.workspaces,
+            note: "Local cache from a prior `connect` \u2014 informational only; the env PAT is the active bearer."
+          };
+        } else {
+          body.cachedIdentity = null;
+          body.hint = "Run `connect <your-databrain-email>` to populate identity metadata locally for richer whoami output. The env PAT will continue to be the active bearer regardless.";
+        }
+        return toolSuccess(JSON.stringify(body, null, 2));
+      }
+      if (auth.source === "cached-pat") {
+        const op = auth.operator;
+        const expiresInDays = Math.max(
+          0,
+          Math.round((op.expiresAt - Date.now()) / (24 * 60 * 60 * 1e3))
+        );
+        return toolSuccess(
+          JSON.stringify(
+            {
+              status: "connected",
+              activeBearer: "cached-pat",
+              email: op.email,
+              userId: op.userId,
+              role: op.role,
+              workspaces: op.workspaces,
+              expiresInDays
+            },
+            null,
+            2
+          )
+        );
+      }
+      return toolSuccess(
+        JSON.stringify(
+          {
+            status: "not_connected",
+            activeBearer: auth.source,
+            note: "No operator bound to this MCP session. Calls fall back to the org-level service token (no per-user audit). Either run `connect <email>` to bootstrap interactively, or paste a Personal Access Token into your MCP config as DATABRAIN_PAT."
+          },
+          null,
+          2
+        )
+      );
+    }
+  );
+}
+
+// src/tools/auth/disconnect.ts
+function registerDisconnect(server, client) {
+  server.tool(
+    "disconnect",
+    "Wipe the locally cached operator credential for this Databrain instance. Use when switching Databrain accounts or revoking access on a shared machine. Subsequent calls fall back to the service token until `connect` is run again.",
+    {},
+    DESTRUCTIVE,
+    async () => {
+      const wasConnected = client.getOperator() !== null;
+      const envPatActive = client.getActiveAuth().source === "env-pat";
+      client.clearOperator();
+      const notes = [];
+      if (wasConnected) {
+        notes.push("Local operator credential cleared. Run `connect` again to rebind.");
+      } else {
+        notes.push("No cached operator to clear.");
+      }
+      if (envPatActive) {
+        notes.push(
+          "DATABRAIN_PAT is still set in your MCP env, so API calls continue using that token. Unset it in your MCP config to fully disconnect."
+        );
+      }
+      return toolSuccess(
+        JSON.stringify(
+          { status: "disconnected", wasConnected, notes },
+          null,
+          2
+        )
+      );
+    }
+  );
+}
+
 // src/tools/registry.ts
 function registerAllTools(server, client) {
+  registerConnect(server, client);
+  registerWhoami(server, client);
+  registerDisconnect(server, client);
   registerListDatasources(server, client);
   registerDiscoverDatasourceSchema(server, client);
   registerListDatamarts(server, client);
   registerListWorkspaces(server, client);
-  registerLinkDatamartToWorkspace(server, client);
   registerListDataApps(server, client);
   registerCreateDataApp(server, client);
   registerListApiTokens(server, client);
@@ -4752,6 +5333,7 @@ function registerAllTools(server, client) {
   registerGetEmbedDetails(server, client);
   registerUpdateEmbed(server, client);
   registerCustomizeTheme(server, client);
+  registerGetDemoLink(server, client);
   registerGenerateGuestToken(server, client);
   registerGenerateEmbedCode(server, client);
   registerListDashboards(server, client);
@@ -7764,75 +8346,87 @@ Suggest a sample question based on the tables you described and run it with \`as
 `;
 
 // src/prompts/customize-customer-dashboard.ts
-var customizeCustomerDashboardPrompt = `You are guiding widget CRUD on a specific customer's dashboard embed. This is the "tweak per customer" flow: add, modify, or remove individual widgets (metrics) on a customer's embedded dashboard without touching the template or other customers.
+var customizeCustomerDashboardPrompt = `You are guiding widget CRUD on a specific customer's dashboard. This is the "tweak per customer" flow for a non-technical CS/CX/support user: add, modify, or remove individual widgets for one customer without touching the template or other customers.
+
+**CRITICAL: This is an interactive, step-by-step guide. STOP after each step, show the user what you found, and wait for their input. Never batch multiple steps. Never assume the customer or dashboard.**
 
-**CRITICAL: This is an interactive, step-by-step guide. STOP after each step, show the user what you found, and wait for their input. Never batch multiple steps. Never assume the customer/embed.**
+**Minimum info the user needs to provide: \`clientId\` + \`dashboardName\`.** Everything else (data app, datasource, embed id, integration id) is auto-resolved. NEVER ask the user for any of those.
 
 **Key concepts (read before starting):**
-- **Embed** = a customer's instantiation of a dashboard. Identified by \`embedId\`. Each embed is scoped to one \`clientId\` (the customer/tenant).
-- **Widget** = a single visualization on a dashboard. Stored as \`externalMetrics\` internally. Has two ids: \`metricId\` (user-facing slug, shown in lists) and \`externalMetricId\` (internal uuid, used for updates/deletes).
-- **Per-client scope**: \`remove_widget\` is a per-client soft delete \u2014 it hides the widget for one client only. The widget stays on the template dashboard and on other customers' embeds.
-- **Guest tokens auto-minted**: \`add_widget\`, \`update_widget\`, \`remove_widget\`, and \`generate_widget\` all mint a guest token per call. You do not need to call \`generate_guest_token\` manually for widget operations.
+- **Dashboard** = the named analytics view the customer sees (e.g. "Demo Dashboard", "Airline Marketing"). This is what the user will name.
+- **Workspace** = an optional container grouping dashboards. Only ask for this if the dashboard name is ambiguous.
+- **Client/customer** = the tenant whose copy of the dashboard we're editing. Identified by \`clientId\`.
+- **Widget** = a single visualization on a dashboard. Has two ids: \`metricId\` (slug, shown in lists) and \`externalMetricId\` (uuid, used for update/remove).
+- **Per-client scope**: \`remove_widget\` is a per-client soft delete \u2014 the widget stays on the template dashboard and on other customers' copies.
 
-**Step 1 \u2014 Identify the target embed**
+**Forbidden questions \u2014 DO NOT ASK the user for any of these:**
+- Data app name, \`dataAppName\`
+- Datasource name, \`integrationName\`, \`integrationId\`, \`companyIntegrationId\`
+- Embed id, \`embedId\`
+- External dashboard id, dashboard id, internal UUIDs
+
+If the user offers any of these proactively, accept and use them, but never prompt for them.
+
+**Step 1 \u2014 Identify the customer and dashboard**
 STOP and ASK the user:
-- "Which customer/client are we customizing for?" (the \`clientId\`)
-- "Which embed/dashboard?" (the \`embedId\`)
+- "Which customer/client are we customizing for?" (capture as \`clientId\`)
+- "Which dashboard?" (capture as \`dashboardName\`)
 
-If the user only knows the customer name, call \`list_data_apps\` then \`list_embeds\` (filtered by \`dataAppName\`) and present the matching embeds. Do NOT proceed until you have both \`embedId\` and \`clientId\` confirmed.
+Only ask about workspace if the tool reports the dashboard name is ambiguous across workspaces.
 
 **Step 2 \u2014 Survey the current widgets**
-Call \`list_widgets({ embedId, clientId })\`.
-STOP and present the list: \`{metricId, name, isPublished, createdByUser}\` per widget.
-ASK: "What would you like to change? (add / modify / remove)" \u2014 or more specifically, "Which widgets should I add, update, or remove?"
+Call \`list_widgets({ clientId, dashboardName, workspaceName? })\`.
+STOP and present the list: \`{externalMetricId, metricId, name, isPublished, createdByUser}\` per widget. Keep the \`externalMetricId\` values from this response \u2014 you'll need them verbatim for update/remove. Show the user the human-readable names; the uuids are yours to reference internally.
+ASK: "What would you like to change? (add / modify / remove) \u2014 and which widgets?"
 
 **Step 3a \u2014 ADD a widget**
-This is a business-user flow. NEVER ask the user for a datasource, \`companyIntegrationId\`, \`integrationId\`, or raw SQL unless they explicitly say they want to write SQL. Prefer the two paths below in order.
+Business-user flow. NEVER ask for SQL, datasource, or chart config unless the user explicitly says they want to write raw SQL.
 
 1. **Clone an existing chart** (default \u2014 try this first):
-   - ASK: "Which existing chart should I copy from?" Call \`list_widgets\` on this embed, or on the template embed / another customer's embed, and present the widgets by name. Let the user pick by name.
-   - Call \`add_widget({ embedId, clientId, templateMetricId, name? })\` using the picked widget's \`metricId\`. The tool inherits the query, chart config, and datasource automatically.
+   - ASK: "Which existing chart should I copy from?" Call \`list_widgets\` and present the widgets by name. Let the user pick by name.
+   - Call \`add_widget({ clientId, dashboardName, workspaceName?, templateMetricId, name? })\` using the picked widget's \`metricId\`. Query, chart config, and datasource are inherited automatically.
 
 2. **Describe the chart in plain English** (AI generate \u2014 use if no suitable template exists):
    - ASK: "Describe the chart you want" (e.g., "calls per day over last 30 days").
-   - Call \`generate_widget({ embedId, clientId, userInputs: { prompt: "..." } })\` \u2014 data app and datasource auto-resolve from the embed's existing widgets. Do NOT ask the user for a datasource or data app.
-   - \`embedId\` is optional on \`generate_widget\` (the tool will fall back to the sole data app / sole datasource if absent), but pass it when you have one \u2014 resolution is more reliable.
-   - Review the returned \`draft\` with the user. If they approve, call \`add_widget({ embedId, clientId, body: <draft + externalDashboardIds> })\` to persist.
+   - Call \`generate_widget({ clientId, dashboardName, workspaceName?, userInputs: { prompt: "..." } })\`.
+   - Review the returned \`draft\` with the user. If they approve, call \`add_widget({ clientId, dashboardName, workspaceName?, body: <draft + externalDashboardIds> })\` to persist.
    - If they want changes, re-run \`generate_widget\` with a refined prompt.
-   - If \`generate_widget\` reports "Multiple data apps", pass \`embedId\` or \`dataAppName\`. If it reports "Could not auto-resolve a datasource", ASK the user which datasource to use by NAME (the error lists available options) and retry with \`integrationName: "<name>"\`. Never ask the user for \`integrationId\` or any UUID \u2014 \`integrationName\` alone is enough.
+   - If \`generate_widget\` reports "Could not auto-detect the datasource", STOP and ASK the user to choose: (a) pick an existing chart to copy from (recommended \u2014 call \`list_widgets\`, present widgets by name, then use \`add_widget\` with \`templateMetricId\`); or (b) pick a datasource by name from the list in the error (only if the user already knows it). Wait for the user's choice \u2014 do not guess.
 
 **Advanced \u2014 write SQL directly** (technical users only; ONLY if the user explicitly asks to write SQL):
-- ASK for: \`name\`, \`query\` (SQL), \`chartOptions\`, \`companyIntegrationId\` (use \`list_datasources\`).
-- Call \`add_widget({ embedId, clientId, name, query, chartOptions, companyIntegrationId, ... })\`.
+- ASK for: \`name\`, \`query\` (SQL), \`chartOptions\`.
+- Call \`add_widget({ clientId, dashboardName, name, query, chartOptions })\` \u2014 datasource still auto-resolves from the dashboard.
 
 Show the user the new widget's \`externalMetricId\` and \`metricId\` after each add.
 
 **Step 3b \u2014 UPDATE a widget**
 If the user wants to modify a widget, STOP and ASK:
-- Which widget? (look up its \`externalMetricId\` from Step 2 \u2014 remember, this is the uuid, NOT the \`metricId\` slug)
+- Which widget? (let the user pick by name, then look up the widget's \`externalMetricId\` from the Step 2 \`list_widgets\` response \u2014 this is the uuid, NOT the \`metricId\` slug. If you skipped Step 2, call \`list_widgets\` first to fetch it \u2014 never ask the user for a uuid.)
 - What to change? (name, query, chartOptions, isPublished, etc.)
 
-Call \`update_widget({ externalMetricId, clientId, dataAppName, set: {<partial patch>} })\`.
+Call \`update_widget({ externalMetricId, clientId, dashboardName, workspaceName?, set: {<partial patch>} })\`.
 Show the user the confirmation and list the changed fields.
 
 **Step 3c \u2014 REMOVE a widget**
 If the user wants to remove a widget, STOP and CONFIRM:
-- "This is a per-client soft delete. The widget will be hidden for \`<clientId>\` only \u2014 other customers and the template dashboard are unaffected. Proceed?"
+- "This is a per-customer soft delete. The widget will be hidden for \`<clientId>\` only \u2014 other customers and the template dashboard are unaffected. Proceed?"
 
-Wait for explicit confirmation before calling \`remove_widget({ externalMetricId, clientId, dataAppName })\`.
+Look up the widget's \`externalMetricId\` from the Step 2 \`list_widgets\` response (call it first if you skipped Step 2). Never ask the user for the uuid.
+Wait for explicit confirmation before calling \`remove_widget({ externalMetricId, clientId, dashboardName, workspaceName? })\`.
 
 **Step 4 \u2014 Verify**
-Call \`list_widgets({ embedId, clientId })\` again. Present the updated list and confirm the changes match what the user asked for.
+Call \`list_widgets({ clientId, dashboardName, workspaceName? })\` again. Present the updated list and confirm the changes match what the user asked for.
+
+**Step 5 \u2014 Hand off the demo link**
+Always close with a demo link so the user can verify visually. Call \`get_demo_link({ clientId, dashboardName, workspaceName? })\` \u2014 it returns the same URL the Databrain UI's "Share Demo Link" button generates: a hosted preview page that loads the dashboard exactly as that \`clientId\` will see it. Default expiry is 24h; pass \`expiryHours\` to override.
 
-**Step 5 \u2014 (Optional) regenerate guest token for live preview**
-If the user wants to see the changes in their running app:
-- Remind them: "Existing guest tokens carry the old embed config. Regenerate via \`generate_guest_token({ clientId, dataAppName })\` and reload the frontend to see the changes."
+Present the URL to the user and remind them: (a) only \`isPublished: true\` widgets appear in the preview, so flag any unpublished widgets from the Step 4 \`list_widgets\` output; (b) if they already have the embed wired up in their own app, the cached frontend guest token there must be refreshed before changes appear.
 
 **Important rules:**
 - STOP after each step. Present results and wait for user input before proceeding.
-- Always pass \`externalMetricId\` (uuid) to \`update_widget\` / \`remove_widget\`, NOT the \`metricId\` slug. When in doubt, use \`list_widgets\` output \u2014 but note that \`list_widgets\` shows \`metricId\`, so you may need \`get_embed_details\` or context from \`add_widget\`'s response to find the uuid.
+- Always pass \`externalMetricId\` (uuid) to \`update_widget\` / \`remove_widget\`, NOT the \`metricId\` slug.
+- Never ask for data app, datasource, integration, or embed identifiers \u2014 they all auto-resolve from \`dashboardName\`.
 - Never batch add + update + remove without confirming each one.
-- If the customer-facing effect is not immediate (e.g., guest token cached), say so explicitly in your handoff message.
 
 After completion, suggest: \`brand-my-embed\` if they want to adjust theme, or \`manage-embeds\` if they want to tweak access settings / options.`;
 
@@ -7887,6 +8481,19 @@ function registerAllPrompts(server) {
 
 // src/server.ts
 function createServer(config) {
+  const client = new DatabrainClient(config);
+  const auth = client.getActiveAuth();
+  let operatorBlurb;
+  if (auth.source === "env-pat") {
+    operatorBlurb = "OPERATOR IDENTITY: a Personal Access Token is active via DATABRAIN_PAT. The backend resolves the user behind it \u2014 all calls are role-checked and audited under their account. Do NOT ask the user to connect; their identity is already bound. Use `whoami` if you need to confirm details.\n\n";
+  } else if (auth.source === "cached-pat") {
+    const op = auth.operator;
+    operatorBlurb = `OPERATOR IDENTITY: connected as ${op.email} (${op.role}) via locally cached PAT. All mutations are role-checked and audit-logged under this user. Use \`whoami\` to confirm, \`disconnect\` to switch users.
+
+`;
+  } else {
+    operatorBlurb = "OPERATOR IDENTITY: not connected. On the user's first request, ask once: \"What's your Databrain login email? I'll bind this MCP session to your account so actions are role-checked and audited.\" Then call `connect` with their email. If `connect` reports it could not persist the credential (sandboxed host), suggest the user generate a PAT in Databrain Settings and paste it into their MCP config as DATABRAIN_PAT for a stable bind. If they decline to connect, fall back to service-token mode (calls still work, but mutations are tagged actor=system in the audit log). Do not pester after one ask.\n\n";
+  }
   const server = new McpServer(
     {
       name: "databrain",
@@ -7894,8 +8501,8 @@ function createServer(config) {
       description: "Databrain MCP Server \u2014 embed analytics dashboards and charts into your app. Focused on embed discovery, deterministic embed updates, theming, filters, localization, permissions, and guest token generation."
     },
     {
-      instructions: `Databrain uses two token types \u2014 never confuse them:
-\u2022 SERVICE TOKEN (DATABRAIN_SERVICE_TOKEN): org-level, pre-configured in MCP server config. Used for: list_datasources, discover_datasource_schema, list_datamarts, list_workspaces, link_datamart_to_workspace, list_data_apps, create_data_app, list_api_tokens, create_api_token, rotate_api_token, list_dashboards (workspace scope), ask_question, get_semantic_layer, update_semantic_layer. You already have this \u2014 never ask the user for it.
+      instructions: operatorBlurb + `Databrain uses two token types \u2014 never confuse them:
+\u2022 SERVICE TOKEN (DATABRAIN_SERVICE_TOKEN): org-level, pre-configured in MCP server config. Used for: list_datasources, discover_datasource_schema, list_datamarts, list_workspaces, list_data_apps, create_data_app, list_api_tokens, create_api_token, rotate_api_token, list_dashboards (workspace scope), ask_question, get_semantic_layer, update_semantic_layer. You already have this \u2014 never ask the user for it.
 \u2022 API TOKEN (per data app): scoped to one data app, used for embedding operations (list_embeds, get_embed_details, create_embed, update_embed, generate_guest_token) and data-app scoped dashboard listing. Created/rotated via create_api_token or rotate_api_token during setup.
 
 3 core use cases \u2014 match the user's scenario to the right prompt:
@@ -7921,7 +8528,6 @@ IMPORTANT \u2014 Be interactive. Present results from each tool call and ask the
 Trigger keywords: embed, dashboard, analytics, Databrain, guest token, theme, filters, permissions, datasource, datamart, workspace, metric creation.`
     }
   );
-  const client = new DatabrainClient(config);
   registerAllTools(server, client);
   registerAllResources(server);
   registerAllPrompts(server);