@databrainhq/mcp-server 0.2.10 → 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);
@@ -1990,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,
@@ -2075,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);
@@ -2094,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) => {
@@ -2212,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) => {
@@ -2230,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();
@@ -2253,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) => {
@@ -2276,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.";
@@ -2314,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."
       )
     },
@@ -2368,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: {
@@ -2502,7 +2670,7 @@ var ACCESS_PRESETS = {
     metricCreationMode: "CHAT"
   }
 };
-var fontFamilyEnum = z14.enum([
+var fontFamilyEnum = z13.enum([
   "Inter",
   "Roboto",
   "Open Sans",
@@ -2514,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;
@@ -2535,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) {
@@ -2707,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",
@@ -2804,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")
     },
@@ -2888,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) {
@@ -4918,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);
@@ -4935,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);
@@ -8018,8 +8417,10 @@ Wait for explicit confirmation before calling \`remove_widget({ externalMetricId
 **Step 4 \u2014 Verify**
 Call \`list_widgets({ clientId, dashboardName, workspaceName? })\` again. Present the updated list and confirm the changes match what the user asked for.
 
-**Step 5 \u2014 (Optional) regenerate guest token for live preview**
-If the user wants to see the changes in their running app, regenerate their guest token and reload. The MCP tools mint tokens internally for widget operations; a cached frontend token will not show the changes until refreshed.
+**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.
+
+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.
@@ -8080,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",
@@ -8087,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:
@@ -8114,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);