> ## 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.
# Tools Reference
> All 36 tools available in the Databrain MCP server
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:
```json theme={"dark"}
{
"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 creation of an unpublished workspace-level metric that is not attached to a dashboard | 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 |
### Customer-Scoped Widget Flow
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:
```json theme={"dark"}
{
"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` when you want an unpublished metric scoped to the workspace but not attached to a dashboard.
***
## 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** |