> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usedatabrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows

> Step-by-step guides for the most common MCP server use cases

The MCP server supports guided prompts that walk you through common tasks end-to-end. You can trigger these by asking naturally or by referencing the prompt name directly. Some use cases are direct tool workflows without a named prompt; you can still ask for them in natural language.

### Jump to a workflow

<CardGroup cols={3}>
  <Card title="Embed a Dashboard" icon="window-maximize" href="#embed-an-existing-dashboard">
    Most common starting point
  </Card>

  <Card title="Multi-Tenant Embeds" icon="users" href="#multi-tenant--per-client-embeds">
    Per-client dashboards
  </Card>

  <Card title="Tenant Discovery" icon="address-book" href="#discover-tenants--client-ids">
    Find valid client IDs
  </Card>

  <Card title="Query Data" icon="magnifying-glass-chart" href="#query-data-with-natural-language">
    Natural language to SQL
  </Card>

  <Card title="Semantic Layer" icon="layer-group" href="#populate-the-semantic-layer">
    Better AI querying
  </Card>

  <Card title="Customer Widgets" icon="chart-line" href="#customize-a-customer-dashboard">
    Per-customer widget edits
  </Card>

  <Card title="SQL Migration" icon="code" href="#sql-to-metric-migration">
    Dry-run then apply metrics
  </Card>

  <Card title="Workspace Metrics" icon="square-plus" href="#create-an-unattached-workspace-metric">
    Unattached metric drafts
  </Card>

  <Card title="Brand & Theme" icon="palette" href="#brand-and-theme-an-embed">
    Colors, fonts, layout
  </Card>

  <Card title="Access & Filters" icon="sliders" href="#configure-embed-access-filters-and-localization">
    Self-serve, filters, i18n
  </Card>

  <Card title="Scheduled Reports" icon="calendar-days" href="#scheduled-reports-metadata">
    Report metadata
  </Card>
</CardGroup>

***

## Embed an Existing Dashboard

The most common workflow. You have a dashboard built in the Databrain UI and want to embed it in your application.

**Ask your AI assistant:**

> "Embed my sales dashboard in my React app"

**What happens:**

<Steps>
  <Step title="Discover data apps">
    The assistant calls `list_data_apps` and asks which data app to use when more than one exists.
  </Step>

  <Step title="Ensure API token">
    It checks `list_api_tokens` and creates one with `create_api_token` if needed.
  </Step>

  <Step title="Select workspace and dashboard">
    It calls `list_workspaces`, then `list_dashboards` scoped to the selected workspace.
  </Step>

  <Step title="Create or reuse embed">
    It checks `list_embeds`, then calls `create_embed` with `dashboardId`, `workspaceName`, and `accessSettings: { datamartName }` if a new embed is needed.
  </Step>

  <Step title="Verify and generate runtime assets">
    It verifies with `get_embed_details`, generates a server-side guest token with `generate_guest_token`, and generates framework code with `generate_embed_code`.
  </Step>
</Steps>

**Prompt name:** `embed-existing-dashboard`

**What you get:** A working embed ID, a guest token payload pattern, and frontend code for React, Next.js, Vue, Angular, Svelte, SolidJS, or vanilla JS.

***

## Multi-Tenant / Per-Client Embeds

Each customer gets their own dashboard copy with a stable `clientId`.

**Ask your AI assistant:**

> "Create per-client dashboard embeds for my SaaS app"

**What happens:**

1. Lists data apps and ensures an API token exists.
2. Calls `list_tenants` to discover valid `clientId` values from the tenancy database.
3. Lists dashboards and asks which source or template dashboard to use.
4. Verifies the datamart and tenancy model.
5. Calls `create_embed` once per customer with `clientId`.
6. Generates guest tokens and frontend code.

**Prompt name:** `embed-blank-dashboard`

<Note>
  `clientId` must match between dashboard embed creation and guest token generation. For `create_embed`, pass only `accessSettings: { datamartName }` plus flags the user explicitly requests; the tool fills required access defaults.
</Note>

***

## Discover Tenants / Client IDs

Find valid customer identifiers before creating guest tokens, customer dashboards, widgets, demo links, or scheduled-report views.

**Ask your AI assistant:**

> "List tenants for my Demo Workspace"

> "Find client IDs matching Acme before I edit a dashboard"

**What happens:**

<Steps>
  <Step title="Resolve the workspace">
    The assistant uses `workspaceName` or `workspaceId`; if needed, it calls `list_workspaces` first.
  </Step>

  <Step title="Read the tenancy source">
    It calls `list_tenants`, optionally with `searchValue`, `datasourceId`, `datamartId`, or `limit`.
  </Step>

  <Step title="Pick the right customer">
    It returns tenant labels and values so you can select the correct `clientId` for downstream embed, widget, guest-token, demo-link, or scheduled-report work.
  </Step>
</Steps>

**Prompt name:** Ask naturally. This is usually a preflight for multi-tenant embed, customer-widget, guest-token, demo-link, or scheduled-report workflows.

<Note>
  Prefer `list_tenants` when you need the authoritative customer list. `list_embeds` can show embed configuration, but tenant lookup comes from the workspace tenancy database.
</Note>

***

## Query Data with Natural Language

Ask questions about your data and get answers with chart suggestions.

**Ask your AI assistant:**

> "What was total revenue last month?"

> "Show me the monthly revenue trend for the past year"

> "Compare sales by region, broken down by quarter"

**What happens:**

<Steps>
  <Step title="Discover datamarts">
    The assistant calls `list_datamarts` to see which data models are available.
  </Step>

  <Step title="Check semantic layer">
    It calls `get_semantic_layer` to verify table and column descriptions exist.
  </Step>

  <Step title="Populate if needed">
    If descriptions are missing, it improves them with `update_semantic_layer` or starts semantic-layer generation with `start_semantic_layer_generation`.
  </Step>

  <Step title="Ask the question">
    It sends your question to `ask_question`, which converts it to SQL, executes the query, and returns results with a chart suggestion.
  </Step>
</Steps>

Follow-up questions use conversation context for better accuracy:

> "Now show only the top 5 regions"

**Prompt name:** `query-data`

***

## Populate the Semantic Layer

Bootstrap table and column descriptions to enable natural language querying.

**Ask your AI assistant:**

> "Check the semantic layer quality for my orders datamart and add descriptions"

**What happens:**

<Steps>
  <Step title="Inspect current state">
    Calls `get_semantic_layer` to see the completion score and missing metadata.
  </Step>

  <Step title="Generate descriptions">
    Generates business-friendly table and column descriptions, synonyms, and example questions.
  </Step>

  <Step title="Push updates">
    Writes metadata with `update_semantic_layer` or starts semantic-layer auto-generation with `start_semantic_layer_generation`.
  </Step>

  <Step title="Verify quality">
    Re-checks the semantic layer score and optionally tests a sample `ask_question`.
  </Step>
</Steps>

**Prompt name:** `populate-semantic-layer`

***

## Customize a Customer Dashboard

Add, remove, or modify widgets for one customer's dashboard without affecting the template or other customers.

**Ask your AI assistant:**

> "Add the Calls per Day widget to Acme's dashboard"

> "Remove the billing widget for this client only"

> "Generate a widget showing disqualification reasons and add it to a client's embed"

**What happens:**

<Steps>
  <Step title="Identify customer and dashboard">
    The assistant asks for `clientId` and `dashboardName`; if you do not know the `clientId`, it calls `list_tenants`. It asks for `workspaceName` only if the dashboard name is ambiguous.
  </Step>

  <Step title="Survey widgets">
    It calls `list_widgets` and presents widget names, publish state, `metricId`, and `externalMetricId`.
  </Step>

  <Step title="Add, update, or remove">
    It calls `add_widget`, `generate_widget`, `update_widget`, or `remove_widget` depending on the requested change. Customer-scoped writes are blocked when the dashboard is not tenant-scoped for that `clientId`.
  </Step>

  <Step title="Verify and preview">
    It calls `list_widgets` again, then `get_demo_link` so you can preview exactly what that `clientId` sees.
  </Step>
</Steps>

**Prompt name:** `customize-customer-dashboard`

<Warning>
  `update_widget` and `remove_widget` require `externalMetricId`, which is returned by `list_widgets`. Do not use the user-facing `metricId` slug for those operations.
</Warning>

***

## SQL-to-Metric Migration

Turn warehouse-validated SQL into a Databrain metric/widget on a customer dashboard with a production-safe validation and apply flow.

**Ask your AI assistant:**

> "Validate this SQL as a new metric on my operations dashboard"

> "Dry-run creating this converted query as a metric, then show me the plan"

**What happens:**

<Steps>
  <Step title="Resolve context">
    Calls `list_workspaces`, `list_dashboards`, and `list_widgets` to confirm the target workspace, dashboard, client, and existing metric IDs.
  </Step>

  <Step title="Validate without saving">
    Calls `validate_metric_spec` to resolve data app, datasource, embed ID, dashboard ID, and conflicts.
  </Step>

  <Step title="Dry-run the write">
    Calls `create_or_update_metric_from_query` with `mode: "dry_run"` and shows the exact plan.
  </Step>

  <Step title="Apply after explicit approval">
    Calls `create_or_update_metric_from_query` with `mode: "apply"` and `confirm: "APPLY_TO_PRODUCTION"` only after the user approves.
  </Step>

  <Step title="Verify">
    Calls `list_widgets` and `get_demo_link`.
  </Step>
</Steps>

**Prompt name:** `sql-to-metric-migration`

<Warning>
  The workflow does not apply changes on the first pass. Applying requires the exact confirmation value `APPLY_TO_PRODUCTION`.
</Warning>

***

## Create an Unattached Workspace Metric

Create a workspace-level metric from validated SQL without attaching it to a dashboard. This is useful when you want to stage a metric as unpublished first, then decide later where it should be exposed.

**Ask your AI assistant:**

> "Create an unpublished workspace metric from this validated SQL, but do not attach it to a dashboard"

> "Dry-run a workspace metric called Revenue by Region in my Analytics workspace"

**What happens:**

<Steps>
  <Step title="Resolve workspace context">
    The assistant confirms the target `workspaceName` and datasource context.
  </Step>

  <Step title="Dry-run the metric">
    It calls `create_workspace_metric` with `mode: "dry_run"` to validate the name, SQL, metric ID, datasource, and publish state without writing.
  </Step>

  <Step title="Review the plan">
    It shows the validation result and confirms that the metric will be workspace-level, unpublished by default, and not attached to any dashboard.
  </Step>

  <Step title="Apply after explicit approval">
    It calls `create_workspace_metric` with `mode: "apply"` and `confirm: "APPLY_TO_PRODUCTION"` only after you approve the write.
  </Step>
</Steps>

**Prompt name:** Ask naturally. Use `sql-to-metric-migration` instead when the metric should become a customer-dashboard widget.

<Warning>
  `create_workspace_metric` uses a service token and does not publish or attach the metric by default. Applying requires the exact confirmation value `APPLY_TO_PRODUCTION`.
</Warning>

***

## Brand and Theme an Embed

Customize colors, fonts, chart styles, responsive breakpoints, cards, and access presets to match your product.

**Ask your AI assistant:**

> "Make my embed match our brand: primary color #4F46E5, dark mode, Inter font"

> "Apply the corporate theme preset and hide the dashboard name"

**What happens:**

1. Identifies the target embed via `list_embeds` or `get_embed_details`.
2. Applies theme changes through `customize_embed_theme`.
3. Uses `update_embed` for advanced patches such as UI options, filters, localization, or permissions.
4. Regenerates the guest token if the frontend needs the new configuration.

**Prompt name:** `brand-my-embed`

***

## Configure Embed Access, Filters, and Localization

Enable self-serve analytics, add filters, localize embed text, or tighten permissions after an embed already exists.

**Ask your AI assistant:**

> "Enable metric creation on my embed with the visual builder"

> "Add a date range filter and a region dropdown to my dashboard"

> "Set up French translations for my embed"

> "Lock down this embed so users can only view, not edit"

**What happens:**

<Steps>
  <Step title="Inspect current settings">
    The assistant calls `list_embeds` or `get_embed_details` to inspect the current access settings, filters, localization, and options.
  </Step>

  <Step title="Patch the embed">
    It calls `update_embed` for access settings, filters, localization, permissions, and advanced embed options. For self-serve metric creation, it sets metric-creation access flags and the requested mode, such as `DRAG_DROP` or `CHAT`.
  </Step>

  <Step title="Refresh runtime configuration">
    If frontend behavior depends on guest-token permissions or filters, it regenerates the guest token with `generate_guest_token`.
  </Step>

  <Step title="Verify">
    It re-checks the embed with `get_embed_details` and can generate a demo link with `get_demo_link` for a tenant-scoped dashboard.
  </Step>
</Steps>

**Prompt name:** Ask naturally. For purely visual changes, use `brand-my-embed`.

***

## Scheduled Reports Metadata

Review scheduled report configuration for a customer/dashboard scope.

**Ask your AI assistant:**

> "List scheduled reports for this client's dashboard"

**What happens:**

1. Resolves the dashboard by `dashboardName` and optional `workspaceName`, or by `embedId`.
2. Calls `list_scheduled_reports` with `clientId`.
3. Returns schedule metadata such as subject, next scheduled time, recipient count, chart count, and download format.

<Note>
  This workflow lists configured schedules only.
</Note>