Skip to main content
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

Embed a Dashboard

Most common starting point

Multi-Tenant Embeds

Per-client dashboards

Tenant Discovery

Find valid client IDs

Query Data

Natural language to SQL

Semantic Layer

Better AI querying

Customer Widgets

Per-customer widget edits

SQL Migration

Dry-run then apply metrics

Workspace Metrics

Unattached metric drafts

Brand & Theme

Colors, fonts, layout

Access & Filters

Self-serve, filters, i18n

Scheduled Reports

Report metadata

​
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:
1

Discover data apps

The assistant calls list_data_apps and asks which data app to use when more than one exists.
2

Ensure API token

It checks list_api_tokens and creates one with create_api_token if needed.
3

Select workspace and dashboard

It calls list_workspaces, then list_dashboards scoped to the selected workspace.
4

Create or reuse embed

It checks list_embeds, then calls create_embed with dashboardId, workspaceName, and accessSettings: { datamartName } if a new embed is needed.
5

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.
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
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.

​
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:
1

Resolve the workspace

The assistant uses workspaceName or workspaceId; if needed, it calls list_workspaces first.
2

Read the tenancy source

It calls list_tenants, optionally with searchValue, datasourceId, datamartId, or limit.
3

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.
Prompt name: Ask naturally. This is usually a preflight for multi-tenant embed, customer-widget, guest-token, demo-link, or scheduled-report workflows.
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.

​
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:
1

Discover datamarts

The assistant calls list_datamarts to see which data models are available.
2

Check semantic layer

It calls get_semantic_layer to verify table and column descriptions exist.
3

Populate if needed

If descriptions are missing, it improves them with update_semantic_layer or starts semantic-layer generation with start_semantic_layer_generation.
4

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.
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:
1

Inspect current state

Calls get_semantic_layer to see the completion score and missing metadata.
2

Generate descriptions

Generates business-friendly table and column descriptions, synonyms, and example questions.
3

Push updates

Writes metadata with update_semantic_layer or starts semantic-layer auto-generation with start_semantic_layer_generation.
4

Verify quality

Re-checks the semantic layer score and optionally tests a sample ask_question.
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:
1

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.
2

Survey widgets

It calls list_widgets and presents widget names, publish state, metricId, and externalMetricId.
3

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.
4

Verify and preview

It calls list_widgets again, then get_demo_link so you can preview exactly what that clientId sees.
Prompt name: customize-customer-dashboard
update_widget and remove_widget require externalMetricId, which is returned by list_widgets. Do not use the user-facing metricId slug for those operations.

​
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:
1

Resolve context

Calls list_workspaces, list_dashboards, and list_widgets to confirm the target workspace, dashboard, client, and existing metric IDs.
2

Validate without saving

Calls validate_metric_spec to resolve data app, datasource, embed ID, dashboard ID, and conflicts.
3

Dry-run the write

Calls create_or_update_metric_from_query with mode: "dry_run" and shows the exact plan.
4

Apply after explicit approval

Calls create_or_update_metric_from_query with mode: "apply" and confirm: "APPLY_TO_PRODUCTION" only after the user approves.
5

Verify

Calls list_widgets and get_demo_link.
Prompt name: sql-to-metric-migration
The workflow does not apply changes on the first pass. Applying requires the exact confirmation value APPLY_TO_PRODUCTION.

​
Create an Unattached Workspace Metric

Create or update 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, fix SQL on an existing workspace metric, or refresh Dimensions/Measures after a query change. 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”
“Update the SQL on my existing workspace metric and refresh its Dimensions and Measures”
What happens:
1

Resolve workspace context

The assistant confirms the target workspaceName and datasource context (via list_workspaces / discover_datasource_schema).
2

Dry-run the metric

It calls create_workspace_metric with mode: "dry_run" to validate the name, SQL, optional metricId, datasource, and publish state without writing. When updating, the same metricId must be carried through dry-run and apply.
3

Review the plan

It shows the validation result and output columns. On create, the metric will be workspace-level, unpublished by default, and unattached. On update, the existing metric is rewritten in place and Dimensions/Measures are re-derived from the new SQL while publish/archived/draft state is preserved.
4

Apply after explicit approval

It calls create_workspace_metric with mode: "apply" and confirm: "APPLY_TO_PRODUCTION" only after you approve the write.
Prompt name: sql-to-workspace-metric. Use sql-to-metric-migration instead when the metric should become a customer-dashboard widget.
create_workspace_metric uses a service token, upserts on metricId, and does not publish or attach the metric by default. Applying requires the exact confirmation value APPLY_TO_PRODUCTION.

​
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:
1

Inspect current settings

The assistant calls list_embeds or get_embed_details to inspect the current access settings, filters, localization, and options.
2

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.
3

Refresh runtime configuration

If frontend behavior depends on guest-token permissions or filters, it regenerates the guest token with generate_guest_token.
4

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.
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.
This workflow lists configured schedules only.