Tools Reference

The MCP server provides 36 tools organized by category. Your AI assistant picks the right tools automatically based on what you ask.

Datasource and workspace setup are completed in the Databrain UI. Datamarts can be planned with create_datamart in dry_run mode and created only with confirm: "APPLY_TO_PRODUCTION".

Auth Modes

Auth	Used for
Service Token	Org-level discovery, tenant lookup, data app and API token management, dashboard listing by workspace, semantic layer operations, natural language querying, datamart creation, and workspace-level metric creation
API Token	Embed operations, guest token generation, data-app-scoped dashboard listing, widget operations, demo links, and scheduled report metadata
No Databrain API call	Code generation or identity checks that do not call Databrain APIs

Production write tools default to dry-run where supported and require explicit confirmation before applying changes.

Session & Identity

Tool	Description	Auth
`whoami`	Return the credential mode currently used for API calls	No Databrain API call

Use whoami before mutating operations when you need to confirm whether the session is running with a service token or an API token.

Infrastructure - Exploration and Setup

6 tools for discovering infrastructure and managing production-safe datamart setup.

Tool	Description	Auth
`list_datasources`	List active datasources in your organization	Service Token
`discover_datasource_schema`	Inspect tables and columns in a datasource	Service Token
`list_datamarts`	List datamarts with table counts and semantic layer scores	Service Token
`list_workspaces`	List workspaces with datamart and datasource connections	Service Token
`sync_datasource`	Trigger a datasource schema sync to refresh table and column metadata	Service Token
`create_datamart`	Dry-run or apply creation of a datamart from selected tables and relationships	Service Token

`create_datamart` Safety

create_datamart defaults to mode: "dry_run" and returns a preview of the datamart configuration. Applying the write requires:

{
  "mode": "apply",
  "confirm": "APPLY_TO_PRODUCTION"
}

Key inputs include name, datasourceName, tableList, relationships, optional tenancySettings, or an advanced JSON configuration.

Data Apps & Tokens

6 tools for managing data apps, tenants, and API tokens. These are usually handled automatically during embed setup.

Tool	Description	Auth
`list_data_apps`	List data apps in your organization, optionally filtered by workspace	Service Token
`list_tenants`	List available tenants/clients from the workspace tenancy database	Service Token
`create_data_app`	Create a new data app	Service Token
`list_api_tokens`	List API tokens for a data app; omit `dataAppName` to auto-resolve	Service Token
`create_api_token`	Create and activate an API token for the current MCP session	Service Token
`rotate_api_token`	Rotate an API token and activate the replacement for the session	Service Token

API tokens are scoped to one data app. The MCP server can create or rotate them when DATABRAIN_SERVICE_TOKEN is configured, so users should not paste API tokens into chat. Use list_tenants to find authoritative clientId values before creating guest tokens or editing tenant-scoped dashboards.

Embeds

6 tools for creating, configuring, previewing, and theming embedded dashboards.

Tool	Description	Auth
`create_embed`	Create a standard embed or a multi-tenant dashboard embed with `clientId`	API Token
`list_embeds`	List embed configurations; use `list_tenants` for authoritative client discovery	API Token
`get_embed_details`	Get full embed configuration including access settings and theme	API Token
`update_embed`	Patch embed access settings, permissions, options, filters, localization, theme, or name	API Token
`customize_embed_theme`	Apply theme presets, colors, fonts, cards, chart appearance, responsive layout, or access presets	API Token
`get_demo_link`	Generate the hosted preview URL for a dashboard embed scoped to a `clientId`	API Token

Embed Creation Shape

For standard dashboard embeds, pass dashboardId, workspaceName, and accessSettings: { datamartName }. For per-client dashboard embeds, also pass clientId. The tool fills required isAllow* access settings with secure defaults, so only pass the flags the user explicitly wants enabled.

Theme and Advanced Config

Use customize_embed_theme for visual theming and access presets. Use update_embed for advanced embed changes such as filters, localization, permissions, or embed options.

Demo Links

get_demo_link returns the same kind of hosted preview URL as the Databrain UI’s “Share Demo Link” flow. It uses DATABRAIN_DEMO_DOMAIN when configured.

Runtime Integration

2 tools for generating guest tokens and frontend integration code.

Tool	Description	Auth
`generate_guest_token`	Generate a server-side guest token for frontend embedding	API Token
`generate_embed_code`	Generate code for React, Next.js, Vue, Angular, Svelte, SolidJS, or vanilla HTML	No Databrain API call

Guest tokens should be generated in your server-side application and passed to the frontend component. Never expose API tokens in browser code.

Query & Semantic Layer

5 tools for natural language querying and data documentation.

Tool	Description	Auth
`ask_question`	Ask a natural language question; returns data, SQL reasoning, and chart suggestion	Service Token
`get_semantic_layer`	Inspect semantic layer metadata, synonyms, and completion score	Service Token
`update_semantic_layer`	Add or update table/column descriptions, synonyms, example questions, and context	Service Token
`start_semantic_layer_generation`	Start semantic-layer auto-generation for a datamart	Service Token
`get_semantic_layer_generation_status`	Poll the semantic-layer generation job status	Service Token

ask_question requires a datamart and a populated semantic layer. If results are poor, inspect the semantic layer first and improve descriptions before re-running the question.

Dashboards & Widgets

9 tools for dashboard discovery, workspace-level metrics, and customer-scoped widget management.

Tool	Description	Auth
`list_dashboards`	List dashboards globally, by workspace, or by data app	Service Token / API Token
`list_widgets`	List widgets on a customer dashboard; returns `externalMetricId`, `metricId`, name, publish state, and creator	API Token
`validate_metric_spec`	Validate a SQL-backed metric target without saving it	API Token
`create_or_update_metric_from_query`	Dry-run or apply a SQL-backed metric create/update	API Token
`create_workspace_metric`	Dry-run or apply create-or-update of a workspace-level metric (unpublished/unattached by default). Pass an existing `metricId` to update in place and re-hydrate Dimensions/Measures from the new SQL	Service Token
`add_widget`	Add a widget by cloning a template widget, supplying a metric configuration, or using a generated draft	API Token
`update_widget`	Patch a widget by `externalMetricId` for one customer’s dashboard	API Token
`remove_widget`	Soft-delete a widget for one `clientId` only	API Token
`generate_widget`	Generate a widget draft from a natural-language prompt; does not persist by itself	API Token

For non-technical widget workflows, provide clientId and dashboardName; include workspaceName only if dashboard names are ambiguous. If you do not know the clientId, call list_tenants with the workspace first. The tools resolve data app, datasource, embed ID, and integration details automatically. Use externalMetricId for update_widget and remove_widget. Do not use the user-facing metricId slug for those operations.

SQL-to-Metric Safety

create_or_update_metric_from_query and create_workspace_metric default to mode: "dry_run". Applying requires:

{
  "mode": "apply",
  "confirm": "APPLY_TO_PRODUCTION"
}

Use validate_metric_spec first for dashboard-attached metric/widget changes, then dry-run, then apply only after the user reviews the plan. Use create_workspace_metric for internal (non-embed) workspace metrics — create by omitting metricId, or update by passing an existing metricId so the query and Dimensions/Measures are rewritten in place while publish/archived/draft state is preserved.

`create_workspace_metric` Upsert Behavior

create_workspace_metric upserts on metricId:

Omit metricId to create. The slug is derived from name, so re-running with the same name targets the same metric rather than creating a duplicate.
Pass an existing metricId to update that metric in place. The new SQL is saved and Dimensions/Measures are re-derived from the query output columns so the metric editor stays populated.
On update, archived/draft and publish state are preserved. The metric stays unattached to any dashboard unless you publish/attach it as a separate step.

Scheduled Reports

Tool	Description	Auth
`list_scheduled_reports`	List configured scheduled reports for a specific client/dashboard embed	API Token

This tool returns schedule metadata such as subject, next scheduled time, recipient count, chart count, and download format.

Tool Count

Category	Count
Session & Identity	1
Infrastructure	6
Data Apps & Tokens	6
Embeds	6
Runtime Integration	2
Query & Semantic Layer	5
Dashboards & Widgets	9
Scheduled Reports	1
Total	36

Embedding Setup

MCP Server

Framework Integration

Component Options

Authentication & Security

Filtering & Personalization

Customization

Events & Interactions

End-User Features

AI Chat Mode

Self-Hosted Deployment

Solution Patterns

Testing & Debugging

Migration & Legacy

Additional Resources

Auth Modes

Session & Identity

Infrastructure - Exploration and Setup

`create_datamart` Safety

Data Apps & Tokens

Embeds

Embed Creation Shape

Theme and Advanced Config

Demo Links

Runtime Integration

Query & Semantic Layer

Dashboards & Widgets

Customer-Scoped Widget Flow

SQL-to-Metric Safety

`create_workspace_metric` Upsert Behavior

Scheduled Reports

Tool Count

​Auth Modes

​Session & Identity

​Infrastructure - Exploration and Setup

​create_datamart Safety

​Data Apps & Tokens

​Embeds

​Embed Creation Shape

​Theme and Advanced Config

​Demo Links

​Runtime Integration

​Query & Semantic Layer

​Dashboards & Widgets

​Customer-Scoped Widget Flow

​SQL-to-Metric Safety

​create_workspace_metric Upsert Behavior

​Scheduled Reports

​Tool Count

Auth Modes

Session & Identity

Infrastructure - Exploration and Setup

`create_datamart` Safety

Data Apps & Tokens

Embeds

Embed Creation Shape

Theme and Advanced Config

Demo Links

Runtime Integration

Query & Semantic Layer

Dashboards & Widgets

Customer-Scoped Widget Flow

SQL-to-Metric Safety

`create_workspace_metric` Upsert Behavior

Scheduled Reports

Tool Count