MCP Server
MCP tools reference
Every tool the Databrain MCP server offers, what it changes, and the access it needs.
Your AI app picks the tools. You do not call them by name, but the names help you read what the app did.
How to read the tables:
- Changes: No means the tool only reads. Yes means it creates, edits, deletes or issues a credential.
- Hosted access: the access the hosted connector needs. A local server with a service token can use every tool its token allows.
- Confirm: the tool runs a dry run by default and changes live data only with
confirm: "APPLY_TO_PRODUCTION". The AI app must ask you for this value. It must never type it for you.
Some tools mint a guest token for their own use and never show it. They count as Yes under Changes.
Identity
| Tool | What it does | Changes | Hosted access |
|---|---|---|---|
whoami | Hosted: your name, company, access and the workspaces you approved. Local: which credential the server uses. | No | none |
Datasources, datamarts and workspaces
| Tool | What it does | Changes | Hosted access |
|---|---|---|---|
list_datasources | List connected datasources | No | mcp:datamarts:read |
discover_datasource_schema | Show the tables and columns of a datasource | No | mcp:datamarts:read |
list_datamarts | List datamarts | No | mcp:datamarts:read |
list_workspaces | List workspaces and their datamarts. Hosted: only the ones you approved | No | mcp:datamarts:read |
sync_datasource | Start a schema sync | Yes | mcp:datamarts:write |
create_datamart | Plan or create a datamart from tables and relationships. Confirm | Yes | mcp:datamarts:write |
create_workspace | Hosted only. Create a workspace. Needs the All workspaces I can access grant and a role that may create one | Yes | mcp:datamarts:write |
You connect a datasource in the app, not over MCP.
Data apps and tokens
| Tool | What it does | Changes | Hosted access |
|---|---|---|---|
list_data_apps | List data apps | No | mcp:dashboards:read |
list_tenants | List the client IDs in your tenancy database | No | mcp:dashboards:read |
create_data_app | Create a data app | Yes | mcp:embeds:write |
list_api_tokens | List a data app’s API tokens | No | mcp:embeds:write |
create_api_token | Create and activate an API token | Yes | mcp:embeds:write |
rotate_api_token | Rotate an API token | Yes | mcp:embeds:write |
Embeds
| Tool | What it does | Changes | Hosted access |
|---|---|---|---|
create_embed | Create an embed, standard or per client with clientId | Yes | mcp:embeds:write |
list_embeds | List embeds | No | mcp:dashboards:read |
get_embed_details | Read one embed | No | mcp:dashboards:read |
update_embed | Change access settings, options, filters and translations | Yes | mcp:embeds:write |
customize_embed_theme | Apply a theme preset, colors, fonts, cards and chart styles | Yes | mcp:embeds:write |
get_demo_link | Get the demo link for one client, the same link as Share Demo Link in the app | Yes | mcp:embeds:write |
generate_guest_token | Create a guest token for your frontend (server side) | Yes | mcp:embeds:write |
generate_embed_code | Write integration code for React, Next.js, Vue, Angular, Svelte, SolidJS or plain JavaScript | No | mcp:dashboards:read |
Dashboards
| Tool | What it does | Changes | Hosted access |
|---|---|---|---|
list_dashboards | List dashboards by data app, workspace or all | No | mcp:dashboards:read |
get_dashboard | Read a dashboard and its metrics | No | mcp:dashboards:read |
create_dashboard | Create a workspace dashboard from a list of tiles | Yes | mcp:dashboards:write |
generate_dashboard_tiles | Have AI draft tiles for a dashboard | Yes | mcp:dashboards:write, mcp:query, mcp:embeds:write |
dashboard_snapshot | A PNG of a dashboard or one chart, as the signed-in user sees it. Needs the hosted connector | Yes | mcp:dashboards:read |
list_scheduled_reports | List scheduled reports for a dashboard or client | No | mcp:dashboards:read |
Dashboard releases (local server only)
These move a dashboard from one environment to the next (Settings > Environments). They need a service token. The hosted connector does not offer them.
| Tool | What it does | Changes |
|---|---|---|
list_dashboard_releases | List a dashboard’s releases, newest first, with edits made since the last one | No |
stage_dashboard_release | Always a dry run. Shows what changes and returns the expected_version | No |
publish_dashboard_release | Publish the reviewed release in the next environment. Same dashboard ID and embeds. Confirm | Yes |
rollback_dashboard_release | Go back to an earlier release. Confirm | Yes |
Questions and charts
| Tool | What it does | Changes | Hosted access |
|---|---|---|---|
ask_question | Turn a question into SQL, run it and return rows with a chart | No | mcp:query |
render_metric_tile | Draw a saved metric as a chart or KPI, with no embed or data app. Pass clientId to read it as one client | No | mcp:dashboards:read, mcp:query |
preview_chart | Redraw an ask_question answer as another chart type. No query runs | No | mcp:query |
save_chart_as_dashboard | Save an ask_question answer as a workspace metric on a new dashboard. Confirm | Yes | mcp:dashboards:write, mcp:query |
The chart tiles call render_chart, refresh_widget, drill_down and change_date_range when you use their controls. They need mcp:dashboards:read and mcp:query.
Metrics and widgets
| Tool | What it does | Changes | Hosted access |
|---|---|---|---|
list_widgets | List the widgets on a dashboard. With clientId, the widgets one client sees | No | mcp:dashboards:read |
validate_metric_spec | Check a SQL metric against its dashboard and datasource without saving | Yes | mcp:dashboards:read, mcp:query, mcp:embeds:write |
create_or_update_metric_from_query | Plan or save a SQL metric on a client dashboard. Confirm | Yes | mcp:dashboards:write, mcp:query, mcp:embeds:write |
create_workspace_metric | Plan or save an unpublished workspace metric (no client). Confirm | Yes | mcp:dashboards:write, mcp:query |
add_widget | Add a widget: copy a template metric, send a metric config, or save a generated draft | Yes | mcp:dashboards:write, mcp:embeds:write |
update_widget | Change a widget’s name, SQL, chart settings or publish state | Yes | mcp:dashboards:write, mcp:embeds:write |
remove_widget | Hide a widget for one client only | Yes | mcp:dashboards:write, mcp:embeds:write |
generate_widget | Have AI draft a widget from a prompt. Pass the draft to add_widget to save it | Yes | mcp:dashboards:write, mcp:query, mcp:embeds:write |
Widget tools on client dashboards need a clientId (from list_tenants) and a dashboard name. They refuse a dashboard that is not set up per client for that clientId.
SQL Checks Before Saving
add_widget, update_widget, and create_or_update_metric_from_query check your SQL against the customer’s data before they save it. They also check the SQL a chart builds from its settings: pivot tables, time series, and charts on a custom table or join. The result says what happened:
| Result | What it means |
|---|---|
| Blocked | The SQL is wrong. Nothing is saved. The error names the missing table or column and, for a batch, which widget to fix. |
| Saved, “SQL not checked” | The check could not run on the Databrain side. The widget is saved anyway. |
| Saved, check skipped | The SQL has {{variables}}, so the check does not run. |
| “Unknown” | The save was sent, but no answer came back. The change may be saved. For a new widget, call list_widgets and look for it. For an edit, open the widget in Databrain and check the fields you changed. Do not send it again until you know. |
- A batch is all-or-nothing on the check. If one widget is blocked, none are saved. A call takes at most 25 widgets. Send more than 25 in a second call.
add_widgetrefuses ametricIdthat is used twice in one call, or that already exists, and nothing is saved.create_or_update_metric_from_queryaccepts an existingmetricIdand updates that widget in place whenconflictStrategyisupdate. With the default (fail) it refuses.- Every widget needs a dashboard of the data app that owns your API token. A dashboard of another data app is refused.
add_widgetrefuses a chart that uses a saved semantic plan (SEMANTIC_WIDGET_NOT_SUPPORTED). Send it as SQL, or create it in Databrain.update_widgetchecks the SQL only when you change the SQL or the chart settings.- If the data app has no tenant setup, the widgets you save with its token cannot be edited with that token. They show
editable: false, andupdate_widgetanswersNO_TENANT_SCOPE. Edit them in Databrain, or set up tenancy for the data app. - With an older self-hosted backend, the MCP server saves the widget the old way and says “SQL not checked (older backend)”.
SQL Errors
When the SQL fails on create_workspace_metric or one of the tools above, the error names the object and where it is in your SQL:
| Field | Value |
|---|---|
details.object | The missing object, when there is one: kind (table, column, schema, database, function, or object) and name. A syntax error has no object. |
details.position | The line and column in the SQL you sent, and a source. It can be missing. |
details.errorCode | A DBN-QRY-* code. See Error codes. |
details.ref | A short reference to give to support. |
object and position are optional. Use the message and the hint first, then the fields that are present.
source says how precise the position is. engine means the database reported the position and it maps into the SQL you sent. search means Databrain found the first match of the name in your SQL. This also happens on databases that usually report a position, when the position cannot be mapped safely into your SQL. Do not assume the position is exact because of the database name: read source. When Databrain finds no match, the error has no position.
The assistant can fix a typo from this error without calling discover_datasource_schema first. Embedded users, guests, and report emails see the same messages as before.
render_metric_tile returns an error, and does not retry, when the saved SQL of a metric is broken. generate_widget and generate_dashboard_tiles say which tile failed. They do not name tables or columns from SQL they generated.
Semantic layer and semantic model
| Tool | What it does | Changes | Hosted access |
|---|---|---|---|
get_semantic_layer | Read table and column descriptions, synonyms and the completion score | No | mcp:datamarts:read |
update_semantic_layer | Add descriptions, synonyms and example questions | Yes | mcp:datamarts:write |
start_semantic_layer_generation | Start AI generation of descriptions for a datamart | Yes | mcp:datamarts:write |
get_semantic_layer_generation_status | Check generation progress | No | mcp:datamarts:read |
search_semantic_model | Find the model entities that match a question | No | mcp:datamarts:read |
get_semantic_entity | Read one entity and its current content hash | No | mcp:datamarts:read |
propose_semantic_change | Check a full YAML source, a YAML patch or one change, and return the plan. Writes nothing | No | mcp:datamarts:read |
eval_semantic_model | Check model test questions. Runs no SQL | No | mcp:datamarts:read, mcp:query |
apply_semantic_change | Preview by default. Applies live with the reviewed hash. Confirm | Yes | mcp:datamarts:write |
semantic_model_draft | Start or resume a saved authoring draft, choose Auto or Review, accept proposals, Undo, and run checks. Hosted only | Yes | mcp:datamarts:read, mcp:datamarts:write, mcp:query |
Applying a semantic change changes the live model for everyone who uses it. Publishing a model is a human action in Databrain. No MCP tool publishes.
Bryn (hosted connector only)
Bryn is the Databrain AI assistant. These tools run a full Bryn turn as the signed-in user. They need the hosted connector, because a service token has no user.
| Tool | What it does | Hosted access |
|---|---|---|
ask_bryn_metric | Ask or plan a metric in a workspace. Does not save it | mcp:query |
ask_bryn_semantic_model | Ask or plan with the semantic model Bryn | mcp:datamarts:read, mcp:datamarts:write |
ask_bryn_theme | Ask, plan or build a theme draft. Does not save the theme | mcp:embeds:write |
ask_bryn_custom_chart | Ask, plan or build a custom chart draft. Saves and publishes nothing | mcp:custom-charts:write |
The connector also offers the semantic model tools that Databrain serves, such as inspect_semantic_model, read_semantic_model_skill, propose_semantic_model, request_semantic_check and request_semantic_verification. They show up only when the Databrain server offers them.
Custom chart types
| Tool | What it does | Changes | Hosted access |
|---|---|---|---|
custom_chart_scaffold | Return the files of a new chart project. Writes nothing | No | mcp:custom-charts:read |
custom_chart_edit | Change a chart draft with Bryn. Never saves or publishes | Yes | mcp:custom-charts:write |
custom_chart_preview | Build a draft in memory and preview it with sample rows | No | mcp:custom-charts:read |
custom_chart_validate | Check a manifest and bundle. Never saves | No | mcp:custom-charts:read |
custom_chart_upload | Upload a built bundle as a private chart or a new version. Confirm | Yes | mcp:custom-charts:write |
list_custom_charts | List your company’s custom chart types | No | mcp:custom-charts:read |
publish_custom_chart | Publish a version so every builder can use it. Confirm | Yes | mcp:custom-charts:write |
To build a chart on your machine, see the custom chart CLI.
Tools that need APPLY_TO_PRODUCTION
create_datamart, create_or_update_metric_from_query, create_workspace_metric, save_chart_as_dashboard, apply_semantic_change, publish_dashboard_release, rollback_dashboard_release, custom_chart_upload and publish_custom_chart.
Without the value they return a dry-run plan. Read the plan, then give the value to the AI app yourself.