@databrainhq/mcp-server 0.2.3 → 0.2.5

package/dist/index.js

@@ -206,8 +206,8 @@ var DatabrainClient = class {
         return cached;
       }
     }
-    const token = this.getToken(options.auth);
-    if (options.auth !== "none" && !token) {
+    const token = options.token ?? this.getToken(options.auth);
+    if (options.auth !== "none" && !options.token && !token) {
       if (options.auth === "service") {
         throw new DatabrainApiError(
           401,
@@ -236,7 +236,12 @@ var DatabrainClient = class {
           "X-Databrain-Client": MCP_USER_AGENT
         };
         if (token) {
-          headers["Authorization"] = `Bearer ${token}`;
+          if (options.auth === "none") {
+            headers["x-plugin-token"] = token;
+            headers["Origin"] = "https://mcp.usedatabrain.com";
+          } else {
+            headers["Authorization"] = `Bearer ${token}`;
+          }
         }
         const response = await fetch(url, {
           method: options.method,
@@ -585,6 +590,68 @@ var QueryApi = class {
   }
 };
 
+// src/api/widgets-api.ts
+var WidgetsApi = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async listWidgets(embedId, clientId) {
+    return this.client.request({
+      method: "GET",
+      path: "/api/v2/data-app/metrics",
+      auth: "api",
+      query: { embedId, clientId }
+    });
+  }
+  async createMetric(guestToken, body) {
+    return this.client.request({
+      method: "POST",
+      path: "/api/v2/dashboard/createMetric",
+      auth: "none",
+      token: guestToken,
+      body
+    });
+  }
+  async updateMetric(guestToken, body) {
+    return this.client.request({
+      method: "POST",
+      path: "/api/v2/dashboard/updateMetric",
+      auth: "none",
+      token: guestToken,
+      body
+    });
+  }
+  async markArchived(guestToken, body) {
+    return this.client.request({
+      method: "POST",
+      path: "/api/v2/dashboard/markArchived",
+      auth: "none",
+      token: guestToken,
+      body
+    });
+  }
+  async generateMetric(guestToken, body) {
+    return this.client.request({
+      method: "POST",
+      path: "/api/v2/dashboard/generateMetric",
+      auth: "none",
+      token: guestToken,
+      body,
+      timeoutMs: 12e4,
+      noRetryOnTimeout: true
+    });
+  }
+  async fetchEmbeddedMetric(guestToken, metricId) {
+    return this.client.request({
+      method: "GET",
+      path: "/api/v2/dashboard/embeddedMetric",
+      auth: "none",
+      token: guestToken,
+      query: { metricId }
+    });
+  }
+};
+
 // src/api/workspaces-api.ts
 var WorkspacesApi = class {
   constructor(client) {
@@ -863,6 +930,126 @@ var GuestTokenService = class {
   }
 };
 
+// src/services/widget-service.ts
+var isNonEmptyString3 = (v) => typeof v === "string" && v.trim().length > 0;
+var asRecord2 = (v) => {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return null;
+  return v;
+};
+var WidgetService = class {
+  constructor(widgetsApi, embedsApi, dataAppsApi, guestTokenService, discoveryService) {
+    this.widgetsApi = widgetsApi;
+    this.embedsApi = embedsApi;
+    this.dataAppsApi = dataAppsApi;
+    this.guestTokenService = guestTokenService;
+    this.discoveryService = discoveryService;
+  }
+  async resolveEmbedContext(embedId) {
+    const response = await this.embedsApi.getByEmbedId(embedId);
+    const records = Array.isArray(response) ? response : response ? [response] : [];
+    const exact = records.find((r) => r && r.embedId === embedId) || records[0];
+    if (!exact) {
+      throw new Error(`Embed "${embedId}" not found. Run \`list_embeds\` to verify.`);
+    }
+    const metadata = asRecord2(exact.embedMetadata);
+    const externalDashboard = asRecord2(exact.externalDashboard);
+    const dataAppId = isNonEmptyString3(exact.dataAppId) ? exact.dataAppId : null;
+    const externalDashboardId = isNonEmptyString3(exact.externalDashboardId) && exact.externalDashboardId || (externalDashboard && isNonEmptyString3(externalDashboard.externalDashboardId) ? externalDashboard.externalDashboardId : null) || (metadata && isNonEmptyString3(metadata.externalDashboardId) ? metadata.externalDashboardId : null);
+    const dashboardId = isNonEmptyString3(exact.dashboardId) && exact.dashboardId || (metadata && isNonEmptyString3(metadata.dashboardId) ? metadata.dashboardId : null);
+    let dataAppName = metadata && isNonEmptyString3(metadata.dataAppName) ? metadata.dataAppName : null;
+    if (!dataAppName && dataAppId) {
+      try {
+        const apps = await this.dataAppsApi.listDataApps();
+        const match = apps.find((a) => {
+          const n = this.discoveryService.normalizeDataApp(a);
+          return n.dataAppId === dataAppId;
+        });
+        if (match) {
+          dataAppName = this.discoveryService.normalizeDataApp(match).name;
+        }
+      } catch {
+      }
+    }
+    return {
+      embedId,
+      dataAppId,
+      dataAppName,
+      externalDashboardId,
+      dashboardId
+    };
+  }
+  async mintGuestToken(clientId, dataAppName, allowedEmbeds) {
+    const { token } = await this.guestTokenService.generateToken({
+      clientId,
+      dataAppName,
+      ...allowedEmbeds && allowedEmbeds.length > 0 ? { allowedEmbeds } : {},
+      permissions: {
+        isDisableMetricCreation: false,
+        isEnableManageMetrics: true,
+        isEnableMetricUpdation: true,
+        isEnableArchiveMetrics: true
+      }
+    });
+    return token;
+  }
+  /**
+   * Build a create body by cloning a template metric. Fetches the full metric
+   * via the embeddedMetric endpoint and copies structural fields, then lets the
+   * caller override `name`/`metricId`/etc.
+   */
+  async buildCloneBody(guestToken, templateMetricId, overrides, externalDashboardId) {
+    const response = await this.widgetsApi.fetchEmbeddedMetric(
+      guestToken,
+      templateMetricId
+    );
+    const metric = asRecord2(response.externalMetric);
+    if (!metric) {
+      throw new Error(
+        `Template metric "${templateMetricId}" not found or could not be loaded. Response keys: ${Object.keys(
+          response || {}
+        ).join(", ")}. Error: ${JSON.stringify(response?.error ?? null)}`
+      );
+    }
+    const clone = {
+      // Required identity — caller must override or we derive.
+      name: overrides.name || (isNonEmptyString3(metric.name) ? `${metric.name} (copy)` : "Widget"),
+      metricId: overrides.metricId || `${isNonEmptyString3(metric.metricId) && metric.metricId || "widget"}-${Date.now()}`,
+      // Structural fields copied from template.
+      query: metric.query || void 0,
+      metricQuery: metric.metricQuery || void 0,
+      description: metric.description || "",
+      chartOptions: asRecord2(metric.chartOptions) || {},
+      companyId: metric.companyId || void 0,
+      companyIntegrationId: metric.companyIntegrationId || void 0,
+      integrationName: metric.integrationName || void 0,
+      outputColumns: metric.outputColumns || void 0,
+      inputFields: metric.inputFields,
+      isLive: metric.isLive ?? void 0,
+      timeGrain: metric.timeGrain || void 0,
+      selectedGroupBy: metric.selectedGroupBy,
+      isEnableGroupBy: metric.isEnableGroupBy ?? void 0,
+      datasetMetricSettings: metric.datasetMetricSettings,
+      groupBy: metric.groupBy,
+      drillDownSettings: metric.drillDownSettings,
+      limit: metric.limit ?? void 0,
+      // Dashboard attachment — always for the target embed's dashboard.
+      externalDashboardIds: [{ externalDashboardId }],
+      // Defaults that shouldn't be inherited from the template.
+      isCreatedByClient: false,
+      isPublished: true
+    };
+    for (const [key, value] of Object.entries(overrides)) {
+      if (value !== void 0) {
+        clone[key] = value;
+      }
+    }
+    if (!clone.externalDashboardIds || clone.externalDashboardIds.length === 0) {
+      clone.externalDashboardIds = [{ externalDashboardId }];
+    }
+    return clone;
+  }
+};
+
 // src/services/factory.ts
 function createServiceBundle(client) {
   const embedsApi = new EmbedsApi(client);
@@ -872,7 +1059,10 @@ function createServiceBundle(client) {
   const datasourcesApi = new DatasourcesApi(client);
   const guestTokenApi = new GuestTokenApi(client);
   const queryApi = new QueryApi(client);
+  const widgetsApi = new WidgetsApi(client);
   const workspacesApi = new WorkspacesApi(client);
+  const discoveryService = new DiscoveryService();
+  const guestTokenService = new GuestTokenService(guestTokenApi);
   return {
     embedsApi,
     dashboardsApi,
@@ -881,9 +1071,17 @@ function createServiceBundle(client) {
     datasourcesApi,
     workspacesApi,
     queryApi,
+    widgetsApi,
     embedService: new EmbedService(embedsApi, datamartsApi),
-    discoveryService: new DiscoveryService(),
-    guestTokenService: new GuestTokenService(guestTokenApi)
+    discoveryService,
+    guestTokenService,
+    widgetService: new WidgetService(
+      widgetsApi,
+      embedsApi,
+      dataAppsApi,
+      guestTokenService,
+      discoveryService
+    )
   };
 }
 
@@ -1281,6 +1479,7 @@ function registerListDatasources(server, client) {
         return toolSuccess(JSON.stringify({
           count: active.length,
           datasources: active.map((ds) => ({
+            id: ds.id,
             name: ds.name,
             type: ds.dbName || ds.datasourceType || "unknown"
           })),
@@ -4012,6 +4211,324 @@ You can now:
   );
 }
 
+// src/tools/widgets/list-widgets.ts
+import { z as z21 } from "zod";
+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.",
+    {
+      embedId: z21.string().describe("Embed ID (customer dashboard instantiation)"),
+      clientId: z21.string().describe("Client/tenant identifier for this embed")
+    },
+    READ_ONLY,
+    async (params) => {
+      try {
+        const widgets = await services.widgetsApi.listWidgets(
+          params.embedId,
+          params.clientId
+        );
+        if (!Array.isArray(widgets) || widgets.length === 0) {
+          return toolSuccess(
+            `No widgets found on embed "${params.embedId}" for client "${params.clientId}".`
+          );
+        }
+        return toolSuccess(
+          JSON.stringify({
+            count: widgets.length,
+            embedId: params.embedId,
+            clientId: params.clientId,
+            widgets: widgets.map((w) => ({
+              metricId: w.metricId || null,
+              name: w.name || null,
+              isPublished: w.isPublished ?? null,
+              createdByUser: w.createdByUser || null
+            }))
+          })
+        );
+      } catch (err) {
+        if (err instanceof DatabrainApiError) return err.toToolResponse();
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
+// src/tools/widgets/add-widget.ts
+import { z as z22 } from "zod";
+function registerAddWidget(server, client) {
+  const services = createServiceBundle(client);
+  server.tool(
+    "add_widget",
+    "Add a widget (metric) to a customer dashboard embed. Either clone a template via `templateMetricId` (recommended \u2014 inherits query, chartOptions, datasource), or supply a full spec (name + query + chartOptions + companyIntegrationId). Mints a guest token for the clientId internally.",
+    {
+      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."),
+      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)"),
+      query: z22.string().optional().describe("SQL query body (overrides template)"),
+      chartOptions: z22.record(z22.unknown()).optional().describe("Chart config JSON (chart type, colors, legend, axes). Overrides template."),
+      description: z22.string().optional(),
+      companyIntegrationId: z22.string().optional().describe("Datasource ID. Required when not cloning a template."),
+      integrationName: z22.string().optional(),
+      isPublished: z22.boolean().optional().describe("Publish immediately (default true)"),
+      body: z22.record(z22.unknown()).optional().describe("Raw createMetric body passthrough. If provided, used as-is (after defaults). Overrides all other params.")
+    },
+    WRITE_CREATE,
+    async (params) => {
+      try {
+        const ctx = await services.widgetService.resolveEmbedContext(params.embedId);
+        const dataAppName = params.dataAppName || ctx.dataAppName;
+        if (!dataAppName) {
+          return toolError(
+            `Could not resolve dataAppName for embed "${params.embedId}". Pass \`dataAppName\` explicitly or verify the embed exists via \`list_embeds\`.`
+          );
+        }
+        if (!ctx.externalDashboardId) {
+          return toolError(
+            `Embed "${params.embedId}" has no externalDashboardId \u2014 cannot attach a widget. Verify via \`get_embed_details\`.`
+          );
+        }
+        const guestToken = await services.widgetService.mintGuestToken(
+          params.clientId,
+          dataAppName,
+          [params.embedId]
+        );
+        let createBody;
+        if (params.body) {
+          createBody = { ...params.body };
+          if (!createBody.externalDashboardIds || createBody.externalDashboardIds.length === 0) {
+            createBody.externalDashboardIds = [
+              { externalDashboardId: ctx.externalDashboardId }
+            ];
+          }
+        } else if (params.templateMetricId) {
+          const overrides = {};
+          if (params.name !== void 0) overrides.name = params.name;
+          if (params.metricId !== void 0) overrides.metricId = params.metricId;
+          if (params.query !== void 0) overrides.query = params.query;
+          if (params.chartOptions !== void 0) overrides.chartOptions = params.chartOptions;
+          if (params.description !== void 0) overrides.description = params.description;
+          if (params.companyIntegrationId !== void 0) {
+            overrides.companyIntegrationId = params.companyIntegrationId;
+          }
+          if (params.integrationName !== void 0) overrides.integrationName = params.integrationName;
+          if (params.isPublished !== void 0) overrides.isPublished = params.isPublished;
+          createBody = await services.widgetService.buildCloneBody(
+            guestToken,
+            params.templateMetricId,
+            overrides,
+            ctx.externalDashboardId
+          );
+        } else {
+          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.");
+          if (!params.companyIntegrationId) {
+            return toolError(
+              "`companyIntegrationId` is required when not cloning a template. Use `list_datasources` to find the datasource ID, or clone from an existing widget via `templateMetricId`."
+            );
+          }
+          createBody = {
+            name: params.name,
+            metricId: params.metricId || `widget-${Date.now()}`,
+            query: params.query,
+            chartOptions: params.chartOptions || {},
+            description: params.description || "",
+            companyIntegrationId: params.companyIntegrationId,
+            integrationName: params.integrationName,
+            isPublished: params.isPublished ?? true,
+            isCreatedByClient: false,
+            externalDashboardIds: [{ externalDashboardId: ctx.externalDashboardId }]
+          };
+        }
+        const result = await services.widgetsApi.createMetric(guestToken, createBody);
+        if (result.error) {
+          return toolError(
+            `Widget creation failed: ${stringify(result.error)}
+
+Request body sent:
+${JSON.stringify(createBody, null, 2).slice(0, 3e3)}`
+          );
+        }
+        const inserted = result.insert_externalMetrics_one;
+        const newId = inserted?.id || inserted?.metricId || "UNKNOWN_ID";
+        const newMetricId = inserted?.metricId || createBody.metricId;
+        return toolSuccess(
+          `Widget added successfully.
+
+- externalMetricId: \`${newId}\`
+- metricId: \`${newMetricId}\`
+- name: \`${createBody.name}\`
+- embedId: \`${params.embedId}\`
+- clientId: \`${params.clientId}\`
+
+Use \`list_widgets\` to verify, or \`update_widget\`/\`remove_widget\` to adjust.`
+        );
+      } catch (err) {
+        if (err instanceof DatabrainApiError) return err.toToolResponse();
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
+// src/tools/widgets/update-widget.ts
+import { z as z23 } from "zod";
+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.",
+    {
+      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().describe("Data app name the widget lives in (required to mint guest token)"),
+      embedId: z23.string().optional().describe("Optional \u2014 if provided, the guest token is scoped to just this embed."),
+      set: z23.record(z23.unknown()).describe("Partial patch. Keys can include: name, query, chartOptions, description, isPublished, isLive, selectedGroupBy, drillDownSettings, limit, etc.")
+    },
+    WRITE_IDEMPOTENT,
+    async (params) => {
+      try {
+        if (!params.set || Object.keys(params.set).length === 0) {
+          return toolError("`set` must contain at least one field to update.");
+        }
+        const guestToken = await services.widgetService.mintGuestToken(
+          params.clientId,
+          params.dataAppName,
+          params.embedId ? [params.embedId] : void 0
+        );
+        const result = await services.widgetsApi.updateMetric(guestToken, {
+          externalMetricId: params.externalMetricId,
+          set: params.set
+        });
+        if (result.error) {
+          return toolError(
+            `Widget update failed: ${stringify(result.error)}`
+          );
+        }
+        const updated = result.update_externalMetrics_by_pk;
+        const id = updated?.id || params.externalMetricId;
+        const metricId = updated?.metricId || null;
+        return toolSuccess(
+          `Widget updated successfully.
+
+- externalMetricId: \`${id}\`
+` + (metricId ? `- metricId: \`${metricId}\`
+` : "") + `- fields changed: ${Object.keys(params.set).join(", ")}
+
+Use \`list_widgets\` to verify.`
+        );
+      } catch (err) {
+        if (err instanceof DatabrainApiError) return err.toToolResponse();
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
+// src/tools/widgets/remove-widget.ts
+import { z as z24 } from "zod";
+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.",
+    {
+      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().describe("Data app name the widget lives in (required to mint guest token)"),
+      embedId: z24.string().optional().describe("Optional \u2014 scopes the guest token to this embed.")
+    },
+    DESTRUCTIVE,
+    async (params) => {
+      try {
+        const guestToken = await services.widgetService.mintGuestToken(
+          params.clientId,
+          params.dataAppName,
+          params.embedId ? [params.embedId] : void 0
+        );
+        const result = await services.widgetsApi.markArchived(guestToken, {
+          id: params.externalMetricId,
+          clientId: params.clientId
+        });
+        if (result.error) {
+          return toolError(
+            `Widget removal failed: ${stringify(result.error)}`
+          );
+        }
+        return toolSuccess(
+          `Widget removed for client "${params.clientId}".
+
+- externalMetricId: \`${params.externalMetricId}\`
+- clientId: \`${params.clientId}\`
+
+Note: this is a per-client soft delete. The widget remains available for other clients and on the source dashboard.`
+        );
+      } catch (err) {
+        if (err instanceof DatabrainApiError) return err.toToolResponse();
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
+// src/tools/widgets/generate-widget.ts
+import { z as z25 } from "zod";
+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 (query, metadata) the caller can review and pass to `add_widget`. Mints a guest token internally.",
+    {
+      clientId: z25.string().describe("Client/tenant identifier"),
+      dataAppName: z25.string().describe("Data app name (required to mint guest token)"),
+      integrationId: z25.string().describe("Datasource ID to generate the widget against. Use `list_datasources` to find."),
+      integrationName: z25.string().describe("Datasource name (matches integrationId)"),
+      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 \u2014 scopes the guest token to this embed.")
+    },
+    READ_ONLY,
+    async (params) => {
+      try {
+        const guestToken = await services.widgetService.mintGuestToken(
+          params.clientId,
+          params.dataAppName,
+          params.embedId ? [params.embedId] : void 0
+        );
+        const result = await services.widgetsApi.generateMetric(guestToken, {
+          integrationId: params.integrationId,
+          integrationName: params.integrationName,
+          userInputs: params.userInputs
+        });
+        const resultRec = result;
+        if (resultRec.error) {
+          return toolError(
+            `Widget generation failed: ${stringify(resultRec.error)}`
+          );
+        }
+        return toolSuccess(
+          JSON.stringify({
+            message: "Draft generated. Review the `query` and `result` fields below, then pass to `add_widget` (using raw `body` passthrough) to persist.",
+            draft: {
+              query: resultRec.query ?? null,
+              result: resultRec.result ?? null,
+              metaData: resultRec.metaData ?? null,
+              timeTaken: resultRec.timeTaken ?? null,
+              error: resultRec.error ?? null
+            }
+          })
+        );
+      } catch (err) {
+        if (err instanceof DatabrainApiError) return err.toToolResponse();
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
 // src/tools/registry.ts
 function registerAllTools(server, client) {
   registerListDatasources(server, client);
@@ -4035,6 +4552,11 @@ function registerAllTools(server, client) {
   registerAskQuestion(server, client);
   registerGetSemanticLayer(server, client);
   registerUpdateSemanticLayer(server, client);
+  registerListWidgets(server, client);
+  registerAddWidget(server, client);
+  registerUpdateWidget(server, client);
+  registerRemoveWidget(server, client);
+  registerGenerateWidget(server, client);
 }
 
 // src/resources/content/getting-started.ts
@@ -6484,7 +7006,7 @@ tenant. For example, filter by department or user role within an organization.
 // src/resources/content/use-case-guides.ts
 var useCaseGuidesContent = `# Databrain Use Case Guides
 
-Databrain supports 4 core use cases for embedding analytics. Each maps to a specific MCP prompt and tool sequence.
+Databrain supports 3 core use cases for embedding analytics. Each maps to a specific MCP prompt and tool sequence.
 
 ---
 
@@ -6501,15 +7023,7 @@ Databrain supports 4 core use cases for embedding analytics. Each maps to a spec
 **Tool sequence:** \`list_data_apps\` \u2192 \`list_datamarts\` \u2192 \`create_embed\` with \`clientId\` (per client) \u2192 \`generate_guest_token\` \u2192 \`generate_embed_code\`
 **Key concepts:** \`clientId\` for tenant isolation, \`templateDashboardId\` for cloning, \`tableTenancySettings\` for row-level security.
 
-## Use Case 3: Enable Metric Creation
-**When to use:** You want end-users to build their own metrics/charts on embedded dashboards.
-**Prompt:** \`enable-metric-creation\`
-**Two modes:**
-- **DRAG_DROP:** Visual metric builder \u2014 users drag columns, pick chart types. No AI needed.
-- **CHAT:** AI-powered natural language \u2014 users type questions. Requires LLM connector in Databrain admin.
-**Tool sequence:** \`list_embeds\` \u2192 \`update_embed\` (set accessSettings and options) \u2192 \`generate_guest_token\` (with permissions)
-
-## Use Case 4: Explore and Query Data
+## Use Case 3: Explore and Query Data
 **When to use:** You want to explore available data and ask questions using natural language.
 **Prompt:** \`query-data\` (or \`populate-semantic-layer\` if starting from an empty semantic layer)
 **Path:** Exploration + querying (datasources, datamarts, and workspaces are created in the Databrain UI). The semantic layer is populated via MCP tools.
@@ -6520,17 +7034,17 @@ Databrain supports 4 core use cases for embedding analytics. Each maps to a spec
 
 ## Customization (After Any Setup)
 
-Once an embed exists, use these prompts to customize:
+Once an embed exists, use the \`brand-my-embed\` prompt for theming. For everything else, describe what you need and the assistant uses tools directly:
 
-| Prompt | Purpose |
-|--------|---------|
-| \`brand-my-embed\` | Colors, fonts, chart styles, theme presets |
-| \`setup-filters\` | String, date, number, SQL, and server-side filters |
-| \`localize-embed\` | Multi-language support and locale settings |
-| \`secure-my-embed\` | Permissions, access controls, role-based tokens |
-| \`manage-embeds\` | List, compare, and manage existing embeds |
-| \`query-data\` | Natural language querying and semantic layer management |
-| \`populate-semantic-layer\` | Auto-generate table/column descriptions for AI features |
+| Task | How |
+|------|-----|
+| Colors, fonts, chart styles | Prompt: \`brand-my-embed\` |
+| Filters (string, date, SQL) | \`update_embed\` with \`options.globalFilterOptions\` via body passthrough |
+| Localization / translations | \`update_embed\` with \`componentAttributes\` via body passthrough |
+| Permissions / access controls | \`update_embed\` + \`generate_guest_token\` with permissions |
+| Metric creation modes | \`update_embed\` accessSettings + \`generate_guest_token\` |
+| Manage / audit embeds | \`list_embeds\` \u2192 \`get_embed_details\` |
+| Semantic layer | Prompt: \`populate-semantic-layer\` or \`get_semantic_layer\` / \`update_semantic_layer\` |
 
 ---
 
@@ -6540,9 +7054,8 @@ Once an embed exists, use these prompts to customize:
 |----------|-------------------|
 | Do you have dashboards in Databrain UI? | Yes \u2192 Use Case 1 |
 | Does each client need their own dashboard? | Yes \u2192 Use Case 2 |
-| Do you want end-users to create metrics? | Yes \u2192 Use Case 3 |
-| Want to explore or query your data? | Yes \u2192 Use Case 4 |
-| Just need to brand/filter/secure? | Use customization prompts |
+| Want to explore or query your data? | Yes \u2192 Use Case 3 |
+| Just need to brand/customize? | Use \`brand-my-embed\` prompt or describe what you need |
 `;
 
 // src/resources/content/permission-schema.ts
@@ -6665,7 +7178,7 @@ var resources = [
   {
     uri: "databrain://use-case-guides",
     name: "Use Case Guides",
-    description: "Summary of 4 core use cases with tool sequences, prompt names, and decision guide",
+    description: "Summary of 3 core use cases with tool sequences, prompt names, and decision guide",
     content: useCaseGuidesContent
   },
   {
@@ -6747,7 +7260,7 @@ Only after they answer, call \`generate_embed_code\` with the \`embedId\`.
 - Prefer existing embeds when the user already has one for their target dashboard.
 - NEVER ask for service or API tokens \u2014 both are handled automatically.
 - \`workspaceName\` comes from dashboard data, not from the data app name.
-- After setup, suggest: \`brand-my-embed\`, \`setup-filters\`, \`localize-embed\`, \`secure-my-embed\`.`;
+- After setup, suggest: \`brand-my-embed\` for theming. For filters, localization, or permissions, just describe what you need and use \`update_embed\` / \`generate_guest_token\` directly.`;
 
 // src/prompts/embed-blank-dashboard.ts
 var embedBlankDashboardPrompt = `You are guiding a multi-tenant setup where each client gets their own blank (or template-based) dashboard. This is ideal for SaaS platforms where each customer sees their own analytics.
@@ -6811,83 +7324,7 @@ The frontend code is the same for all clients \u2014 the \`clientId\` in the gue
 - STOP after each step. Present results and wait for user input before proceeding.
 - When calling \`create_embed\` with \`clientId\`, only pass \`accessSettings: { datamartName }\` \u2014 the tool fills in all required defaults automatically. Do NOT enumerate isAllow* fields.
 - \`clientId\` must be consistent between embed creation and guest token generation.
-- After setup, suggest: \`brand-my-embed\`, \`setup-filters\`, \`enable-metric-creation\`, \`secure-my-embed\`.`;
-
-// src/prompts/enable-metric-creation.ts
-var enableMetricCreationPrompt = `You are helping the user enable end-user metric creation on their embedded dashboards. Databrain supports two modes: DRAG_DROP (visual builder) and CHAT (AI-powered natural language).
-
-**CRITICAL: This is an interactive guide. You MUST stop and ask the user at each decision point before proceeding. Never assume answers.**
-
-**Two Metric Creation Modes:**
-- **DRAG_DROP**: Visual metric builder where users drag columns, choose chart types, and configure metrics. No AI needed.
-- **CHAT**: AI-powered natural language metric creation. Users type questions like "Show me revenue by month" and Databrain generates the metric. Requires an LLM connector configured in the Databrain admin panel.
-
-**Step 1 \u2014 Identify the Embed**
-Call \`list_embeds\` to show available embeds.
-STOP and ASK the user: "Which embed do you want to enable metric creation on?"
-Only after they answer, call \`get_embed_details\` to see current access settings.
-
-**Step 2 \u2014 Choose the Mode**
-STOP and ASK the user:
-- "Which metric creation mode do you want?"
-  - **DRAG_DROP**: Visual builder, no AI dependency
-  - **CHAT**: AI-powered, requires LLM connector setup in Databrain admin
-Do NOT proceed until the user picks a mode.
-
-If they choose CHAT, tell them: "CHAT mode requires an LLM connector configured in the Databrain admin panel (Settings > AI Configuration). Have you set this up?"
-
-**Step 3 \u2014 Update Embed Access Settings**
-Call \`update_embed\` with the embed ID and updated \`accessSettings\`:
-
-For DRAG_DROP mode:
-\`\`\`json
-{
-  "accessSettings": {
-    "isAllowMetricCreation": true,
-    "metricCreationMode": "DRAG_DROP"
-  }
-}
-\`\`\`
-
-For CHAT mode:
-\`\`\`json
-{
-  "accessSettings": {
-    "isAllowMetricCreation": true,
-    "metricCreationMode": "CHAT"
-  }
-}
-\`\`\`
-
-**Step 4 \u2014 Configure Embed Options**
-Call \`update_embed\` (body passthrough with options) to ensure the UI supports metric creation:
-- \`disableMetricCreation\`: false
-- \`hideCreateMetricButton\`: false
-- \`hideChartSettings\`: false (so users can customize their created metrics)
-
-**Step 5 \u2014 Set Guest Token Permissions**
-Remind the user: guest token \`permissions\` override embed \`accessSettings\` at runtime. When generating guest tokens via \`generate_guest_token\`, include:
-\`\`\`json
-{
-  "permissions": {
-    "isDisableMetricCreation": false
-  }
-}
-\`\`\`
-
-**Step 6 \u2014 Verify and Test**
-Call \`get_embed_details\` to verify the settings were applied correctly.
-Tell the user to refresh their embed and look for the "+ Create Metric" button.
-
-If using CHAT mode, remind the user:
-- An LLM connector must be configured in Databrain admin (Settings > AI Configuration)
-- The datamart should have a populated semantic layer for best AI results (use \`get_semantic_layer\` to check, and \`update_semantic_layer\` or the \`populate-semantic-layer\` prompt to populate it)
-
-**Important rules:**
-- STOP and ASK at each decision point. Never skip ahead.
-- Guest token \`permissions\` take precedence over embed \`accessSettings\` \u2014 both must allow metric creation.
-- CHAT mode requires external LLM connector setup (not available via MCP).
-- After enabling, suggest: \`secure-my-embed\` to fine-tune which users get metric creation access.`;
+- After setup, suggest: \`brand-my-embed\` for theming. For filters, metric creation, or permissions, just describe what you need and use \`update_embed\` / \`generate_guest_token\` directly.`;
 
 // src/prompts/brand-my-embed.ts
 var brandMyEmbedPrompt = `You are helping the user brand and visually customize their embedded Databrain dashboard. Follow these steps.
@@ -6964,327 +7401,6 @@ Iterate by calling the relevant tools again with adjusted values. Remember: all
 
 **Reference**: Use \`databrain://theme-reference\` for the full theme schema and \`databrain://web-component-reference\` for all component attributes.`;
 
-// src/prompts/localize-embed.ts
-var localizeEmbedPrompt = `You are helping the user set up multi-language support for their embedded Databrain dashboard. Follow these steps.
-
-**Step 1 \u2014 Identify the Embed and Target Languages**
-Call \`list_embeds\` and ask the user which embed to localize. Then ask:
-- Which languages do they need? (Supported: English, French, Spanish, German, Italian, Portuguese, Chinese, Japanese, Korean, Hindi, Arabic, Russian)
-- What is the default/primary language?
-
-**Step 2 \u2014 Set the Primary Language**
-Use \`update_embed\` (body passthrough with componentAttributes) with the \`language\` parameter set to their primary language code (e.g. "fr" for French).
-
-**Step 3 \u2014 Gather Translations**
-Call \`get_embed_details\` to understand what text is in the dashboard. Then help the user build translations:
-
-Ask the user to list the key text elements in their dashboard:
-- Dashboard title
-- Metric titles and descriptions
-- Filter labels
-- Any footnotes or annotations
-
-For each text element, ask for translations in their target languages. Build translation entries like:
-\`\`\`
-{ key: "Revenue", translations: { fr: "Revenus", es: "Ingresos", de: "Einnahmen" } }
-\`\`\`
-
-**Important rules for translation keys:**
-- Keys must match the dashboard text EXACTLY (case-sensitive)
-- Define longer keys before shorter ones to avoid partial matches
-- If a translation is missing for a language, the original key text is shown as fallback
-
-**Step 4 \u2014 Apply Translations**
-Use \`update_embed\` (body passthrough with componentAttributes.translationDictionary) with the translations.
-
-**Step 5 \u2014 Configure Calendar (if needed)**
-Ask if they need a different calendar system:
-- \`"default"\` \u2014 standard Gregorian calendar
-- \`"ind"\` \u2014 Indian calendar format
-
-Set via \`calendarType\` in \`update_embed\` (body passthrough with componentAttributes).
-
-**Step 6 \u2014 Set Custom Messages**
-Ask if they want to translate system messages:
-- Token expiry message (shown when session expires)
-- Token absent message (shown when no auth token)
-
-Use \`update_embed\` (body passthrough with options.customMessages) with \`tokenExpiry\` and \`tokenAbsent\` in their primary language.
-
-**Step 7 \u2014 Test**
-Tell the user to refresh the embed and verify translations appear correctly. If any text isn't translating, double-check that the key matches exactly.
-
-Remind the user: translations can also be applied per-user at the web component level using the \`translation-dictionary\` attribute, which is useful for dynamically switching languages based on user preferences.
-
-**Tip:** The \`language\`, \`calendarType\`, \`hideDashboardFilters\`, and filter settings are all configurable via \`update_embed\` body passthrough.
-
-**Important:** After changing language or translation settings, existing guest tokens still carry the old configuration. Remind the user to **regenerate guest tokens** (or reload their app) for changes to take effect.`;
-
-// src/prompts/secure-my-embed.ts
-var secureMyEmbedPrompt = `You are helping the user secure and configure permissions for their embedded Databrain dashboard. Follow these steps.
-
-**Step 1 \u2014 Understand User Roles**
-Ask the user about their end-user roles. Common patterns:
-- **Viewer** \u2014 can see data, maybe filter, but can't modify anything
-- **Analyst** \u2014 can export data, drill down, use filters
-- **Builder/Power User** \u2014 can create/edit metrics, change layouts
-- **Admin** \u2014 full access including AI features
-
-Ask: "What roles do your end-users have? What should each role be allowed to do?"
-
-**Step 2 \u2014 Lock Down the Embed Defaults**
-Use \`update_embed\` (body passthrough with options) to set restrictive defaults (principle of least privilege):
-
-\`\`\`
-update_embed(embedId, body: { options: {
-  disableMetricCreation: true,
-  disableMetricUpdation: true,
-  disableMetricDeletion: true,
-  disableManageMetrics: true,
-  disableLayoutCustomization: true,
-  disableSaveLayout: true,
-  disableUnderlyingData: true,
-  disableScheduleEmailReports: true,
-  enableDownloadCsv: false,
-  enableDownloadAllPdf: false)
-\`\`\`
-
-Explain: "We start with everything locked down, then use guest token permissions to grant access per role."
-
-**Step 3 \u2014 Create Role-Based Guest Token Examples**
-Show the user how to generate tokens for each role:
-
-**Viewer (default \u2014 no overrides needed):**
-\`\`\`
-generate_guest_token(clientId, dataAppName)
-\`\`\`
-
-**Analyst (can export and drill down):**
-\`\`\`
-generate_guest_token(clientId, dataAppName, {
-  permissions: {
-    isEnableDownloadMetrics: true,
-    isEnableUnderlyingData: true
-  }
-})
-\`\`\`
-
-**Builder (can create and edit):**
-\`\`\`
-generate_guest_token(clientId, dataAppName, {
-  permissions: {
-    isEnableManageMetrics: true,
-    isEnableMetricUpdation: true,
-    isEnableCustomizeLayout: true
-  }
-})
-\`\`\`
-
-**Admin (full access with AI):**
-\`\`\`
-generate_guest_token(clientId, dataAppName, {
-  permissions: {
-    isEnableManageMetrics: true,
-    isEnableMetricUpdation: true,
-    isEnableCustomizeLayout: true,
-    isEnableDownloadMetrics: true,
-    isEnableUnderlyingData: true
-  }
-})
-\`\`\`
-
-**Step 4 \u2014 Multi-Tenancy Check**
-Ask: "Do different customers/organizations see different data?"
-
-If yes:
-- Explain that \`clientId\` in the guest token controls row-level security
-- The \`clientId\` must match values in the datamart's client column
-- Suggest using \`params.appFilters\` / \`params.dashboardAppFilters\` in \`generate_guest_token\` for server-side row-level filtering
-
-**Step 5 \u2014 Security Checklist**
-Walk through this checklist with the user:
-
-1. \u2705 API token is stored server-side only (never in frontend code)
-2. \u2705 Guest tokens are generated server-side per request
-3. \u2705 Guest tokens have appropriate expiry time
-4. \u2705 Embed defaults are restrictive (locked down in Step 2)
-5. \u2705 Role-based permissions are granted via guest token overrides
-6. \u2705 Multi-tenancy is configured if serving multiple customers
-7. \u2705 Download restrictions are set (\`disableDownloadDataNoFilters\` if needed)
-
-**Step 6 \u2014 Generate Secure Frontend Code**
-Call \`generate_embed_code\` for their framework. Emphasize that the generated code includes a backend route for token generation \u2014 this is the secure pattern.
-
-When reviewing runtime behavior (for example missing \`+ Create Metric\`), verify contract shape explicitly:
-- Guest token request body must send \`permissions\` at top level (not nested inside \`params\`)
-- Include \`dataAppName\` at top level
-- For metric creation flows, ensure \`permissions.isDisableMetricCreation=false\` and \`permissions.isEnableManageMetrics=true\`
-- Confirm embed options do not set \`disableMetricCreation=true\`
-- In browser network response for \`/api/v2/dashboard\`, confirm \`isAllowedToCreateMetrics=true\` and \`metricCreationMode=DRAG_DROP\`
-
-**Important:** After changing embed permissions or access settings, existing guest tokens still carry the old configuration. Remind the user to **regenerate guest tokens** (or reload their app) for changes to take effect.
-
-**Reference**: Use \`databrain://self-serve-reference\` for all permission flags and \`databrain://multi-tenancy-guide\` for row-level security details.`;
-
-// src/prompts/setup-filters.ts
-var setupFiltersPrompt = `You are helping the user configure dashboard filters for their embedded Databrain dashboard. Follow these steps.
-
-**Step 1 \u2014 Understand the Data**
-Call \`list_embeds\` and ask which embed to configure. Then call \`get_embed_details\` to see the current filter configuration.
-
-**Step 2 \u2014 Identify Filter Needs**
-Ask the user:
-- "What filters do your end-users need?" (e.g. date range, region, product category, status)
-- "Should any filters have default values?"
-- "Are there filters you want to hide from end-users?" (e.g. internal IDs)
-- "Do any filters have very large option lists?" (100+ options \u2014 these benefit from SQL-based filters)
-
-**Step 3 \u2014 Configure String Filters**
-For text/category filters, use \`update_embed\` (body passthrough with options.globalFilterOptions) for \`stringFilters\`:
-
-\`\`\`
-stringFilters: [{
-  filterName: "Region",
-  options: [
-    { value: "US", label: "United States" },
-    { value: "EU", label: "Europe" },
-    { value: "APAC", label: "Asia Pacific" }
-  ],
-  defaultOption: "US"
-}]
-\`\`\`
-
-For multi-select defaults, use an array: \`defaultOption: ["US", "EU"]\`
-
-**Step 4 \u2014 Configure Date Filters**
-For date range filters, use \`dateFilters\`:
-
-\`\`\`
-dateFilters: [{
-  filterName: "Date Range",
-  startDate: "2024-01-01",
-  endDate: "2024-12-31",
-  datePresetOptions: [
-    { label: "Last 30 Days", type: "Last", interval: "Days" },
-    { label: "This Quarter", type: "This", interval: "Quarter" },
-    { label: "This Year", type: "This", interval: "Year" }
-  ]
-}]
-\`\`\`
-
-**Step 5 \u2014 Configure Number Filters**
-For numeric range filters, use \`numberFilters\`:
-
-\`\`\`
-numberFilters: [{
-  filterName: "Revenue",
-  min: 0,
-  max: 1000000
-}]
-\`\`\`
-
-**Step 6 \u2014 SQL-Based Filters (for large datasets)**
-If a filter has 100+ options (e.g. company names, product SKUs), use \`sqlFilters\`:
-
-\`\`\`
-sqlFilters: [{
-  filterName: "Company",
-  sql: "SELECT DISTINCT \\"company_name\\" FROM \\"companies\\" ORDER BY \\"company_name\\"",
-  columnName: "company_name"
-}]
-\`\`\`
-
-Explain: "SQL filters dynamically fetch options from the database, so they're always up-to-date and don't bloat the embed configuration."
-
-**Step 7 \u2014 Hide Unnecessary Filters**
-If the user has filters that should be hidden (e.g. internal IDs, tenant columns already handled by clientId):
-
-\`\`\`
-hideDashboardFilters: ["internal_id", "tenant_id"]
-\`\`\`
-
-**Step 8 \u2014 Configure Date Picker Options**
-Ask if they want to hide certain date picker presets:
-
-\`\`\`
-hideDatePickerOptions: ["yesterday", "last week"]
-\`\`\`
-
-**Step 9 \u2014 Metric Filter Position**
-Ask: "Do you want metric-level filters inside the card or outside?"
-- \`"inside"\` \u2014 compact, within each metric card (default)
-- \`"outside"\` \u2014 above the card, more prominent
-
-Also ask if they want cross-metric filtering (\`enableMultiMetricFilters\`).
-
-**Step 10 \u2014 Server-Side Filters (via Guest Token)**
-If the user needs filters that end-users cannot remove (e.g. for security):
-- Explain that \`appFilters\` in \`generate_guest_token\` are server-side enforced
-- These are invisible to the end-user and cannot be overridden
-- Perfect for tenant filtering, role-based data access, or compliance requirements
-
-Show an example:
-\`\`\`
-generate_guest_token(clientId, dataAppName, {
-  params: {
-    appFilters: [{
-      metricId: "metric_123",
-      values: {
-        region: ["US", "CA"]
-      }
-    }]
-  }
-})
-\`\`\`
-
-**Important:** After changing filter settings, existing guest tokens still carry the old configuration. Remind the user to **regenerate guest tokens** (or reload their app) for changes to take effect.
-
-**Reference**: Use \`databrain://filter-reference\` for all filter types, operators, and combination rules.`;
-
-// src/prompts/manage-embeds.ts
-var manageEmbedsPrompt = `You are helping the user manage Databrain embed configurations \u2014 list, compare, and review settings. Follow these steps based on what the user needs.
-
-**Step 1 \u2014 Understand the Task**
-Ask the user what they want to do:
-1. **List and compare embeds** \u2014 see all embeds and their configurations
-2. **Review embed settings** \u2014 audit theme, permissions, and options
-
-**For Listing and Comparing Embeds:**
-1. Call \`list_embeds\` to show all embed configurations
-2. For detailed comparison, call \`get_embed_details\` on each embed the user wants to compare
-3. Present a comparison table showing:
-   - Embed name and ID
-   - Linked dashboard
-   - Theme (preset or custom)
-   - Key permissions (metric creation, downloads, AI pilot)
-   - Multi-tenancy settings
-
-**For Reviewing Embed Settings:**
-1. Call \`get_embed_details\` for the embed
-2. Present a clear summary organized by category:
-
-   **Theme:**
-   - Current preset or custom theme values
-   - Suggest \`customize_embed_theme\` if they want changes
-
-   **Permissions / Access Settings:**
-   - What's enabled vs disabled
-   - Suggest \`update_embed\` for changes
-
-   **Filters:**
-   - Current filter configuration
-   - Suggest \`update_embed\` (body passthrough with options.globalFilterOptions) for changes
-
-   **Internationalization:**
-   - Current language and translations
-   - Suggest \`update_embed\` (body passthrough with componentAttributes) for changes
-
-3. Ask: "Would you like to modify any of these settings?"
-
-**Tips:**
-- Embed IDs are permanent \u2014 even if you rename an embed, the ID stays the same
-- After any embed setting changes, existing guest tokens still carry the old configuration \u2014 **regenerate guest tokens** for changes to take effect`;
-
 // src/prompts/query-data.ts
 var queryDataPrompt = `You are helping the user query their data using natural language. Databrain's AI converts questions into SQL, runs them against the database, and returns results with chart type suggestions.
 
@@ -7441,6 +7557,77 @@ Suggest a sample question based on the tables you described and run it with \`as
 - For very large schemas (50+ tables), start with the most important tables and expand as needed
 `;
 
+// 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.
+
+**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.**
+
+**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.
+
+**Step 1 \u2014 Identify the target embed**
+STOP and ASK the user:
+- "Which customer/client are we customizing for?" (the \`clientId\`)
+- "Which embed/dashboard?" (the \`embedId\`)
+
+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.
+
+**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?"
+
+**Step 3a \u2014 ADD a widget**
+If the user wants to add a widget, STOP and ASK which sourcing mode:
+
+1. **Clone from template** (cheapest, most common):
+   - ASK for the source \`templateMetricId\` \u2014 or call \`list_widgets\` on the template embed / another customer's embed to help pick.
+   - Call \`add_widget({ embedId, clientId, templateMetricId, name? })\`. The tool inherits query, chartOptions, and datasource from the template.
+
+2. **Fresh spec** (SQL + chart config):
+   - ASK for: \`name\`, \`query\` (SQL), \`chartOptions\` (chart type + config), \`companyIntegrationId\` (datasource ID \u2014 use \`list_datasources\` if needed).
+   - Call \`add_widget({ embedId, clientId, name, query, chartOptions, companyIntegrationId, ... })\`.
+
+3. **AI generate** (NL prompt):
+   - ASK for a prompt describing the widget (e.g., "calls per day over last 30 days") and the \`integrationId\` / \`integrationName\` to query against.
+   - Call \`generate_widget({ clientId, dataAppName, integrationId, integrationName, userInputs: { prompt: "..." } })\`.
+   - Review the returned \`draft\` with the user. If they approve, call \`add_widget({ embedId, clientId, body: <draft + externalDashboardIds> })\` to persist.
+   - If they want changes, re-run \`generate_widget\` with a refined prompt.
+
+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)
+- What to change? (name, query, chartOptions, isPublished, etc.)
+
+Call \`update_widget({ externalMetricId, clientId, dataAppName, 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?"
+
+Wait for explicit confirmation before calling \`remove_widget({ externalMetricId, clientId, dataAppName })\`.
+
+**Step 4 \u2014 Verify**
+Call \`list_widgets({ embedId, clientId })\` 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:
+- 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."
+
+**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.
+- 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.`;
+
 // src/prompts/registry.ts
 var prompts = [
   {
@@ -7453,36 +7640,11 @@ var prompts = [
     description: "Multi-tenant blank dashboard setup: each client gets their own dashboard copy via create_embed with clientId",
     content: embedBlankDashboardPrompt
   },
-  {
-    name: "enable-metric-creation",
-    description: "Enable end-user metric creation on embeds: DRAG_DROP (visual) or CHAT (AI-powered) modes",
-    content: enableMetricCreationPrompt
-  },
   {
     name: "brand-my-embed",
     description: "Customize colors, fonts, chart styles, and component theme to match your brand",
     content: brandMyEmbedPrompt
   },
-  {
-    name: "localize-embed",
-    description: "Set up multi-language support with translations and locale settings",
-    content: localizeEmbedPrompt
-  },
-  {
-    name: "secure-my-embed",
-    description: "Configure permissions, access controls, and role-based guest tokens",
-    content: secureMyEmbedPrompt
-  },
-  {
-    name: "setup-filters",
-    description: "Configure dashboard filters: string, date, number, SQL-based, and server-side filters",
-    content: setupFiltersPrompt
-  },
-  {
-    name: "manage-embeds",
-    description: "List, compare, rename, delete embeds and rotate API tokens",
-    content: manageEmbedsPrompt
-  },
   {
     name: "query-data",
     description: "Query your data with natural language: ask questions, get results with chart suggestions, manage the semantic layer",
@@ -7492,6 +7654,11 @@ var prompts = [
     name: "populate-semantic-layer",
     description: "Auto-generate and push table/column descriptions to enable natural language querying on a datamart",
     content: populateSemanticLayerPrompt
+  },
+  {
+    name: "customize-customer-dashboard",
+    description: "Add, modify, or remove widgets on a specific customer's dashboard embed. Per-client scope \u2014 changes only affect that customer.",
+    content: customizeCustomerDashboardPrompt
   }
 ];
 function registerAllPrompts(server) {
@@ -7523,16 +7690,15 @@ function createServer(config) {
 \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.
 \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.
 
-4 core use cases \u2014 match the user's scenario to the right prompt:
+3 core use cases \u2014 match the user's scenario to the right prompt:
 1. Embed existing dashboard \u2192 prompt: embed-existing-dashboard (list_data_apps \u2192 create_api_token \u2192 list_dashboards \u2192 create_embed \u2192 generate_guest_token \u2192 generate_embed_code)
 2. Blank dashboard per client \u2192 prompt: embed-blank-dashboard (list_data_apps \u2192 list_datamarts \u2192 create_embed with clientId per client \u2192 generate_guest_token \u2192 generate_embed_code)
-3. Enable metric creation \u2192 prompt: enable-metric-creation (list_embeds \u2192 update_embed accessSettings \u2192 generate_guest_token with permissions)
-4. Explore & query data \u2192 prompt: query-data (list_datamarts \u2192 get_semantic_layer \u2192 if empty, auto-generate descriptions with update_semantic_layer or use populate-semantic-layer prompt \u2192 ask_question)
+3. Explore & query data \u2192 prompt: query-data (list_datamarts \u2192 get_semantic_layer \u2192 if empty, auto-generate descriptions with update_semantic_layer or use populate-semantic-layer prompt \u2192 ask_question)
 
 Infrastructure CREATION (datasources, datamarts, workspaces) is done in the Databrain UI.
 However, the **semantic layer** is populated and maintained entirely via MCP tools (get_semantic_layer, update_semantic_layer). When the semantic layer is empty, YOU (the assistant) should auto-generate descriptions from table/column names and push them with update_semantic_layer \u2014 do NOT send the user to the UI for this.
 
-After embed setup, customize with: brand-my-embed, setup-filters, localize-embed, secure-my-embed.
+After embed setup, customize with: brand-my-embed prompt for theming. Use update_embed (body passthrough) for filters, localization, and permissions.
 Use generate_guest_token for frontend auth and generate_embed_code for framework snippets.
 For advanced embed configuration (UI toggles, filters, i18n), use update_embed with a body passthrough.
 To diagnose embed issues, use get_embed_details and reason about the response.
@@ -7566,7 +7732,7 @@ async function main() {
     const server = createServer(config);
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    banner(`v${VERSION} ready (24 tools, 11 resources, 10 prompts)`);
+    banner(`v${VERSION} ready (21 tools, 11 resources, 5 prompts)`);
   } catch (error) {
     logger.error("Failed to start server", error);
     process.exit(1);