Skip to Content

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

ToolWhat it doesChangesHosted access
whoamiHosted: your name, company, access and the workspaces you approved. Local: which credential the server uses.Nonone

Datasources, datamarts and workspaces

ToolWhat it doesChangesHosted access
list_datasourcesList connected datasourcesNomcp:datamarts:read
discover_datasource_schemaShow the tables and columns of a datasourceNomcp:datamarts:read
list_datamartsList datamartsNomcp:datamarts:read
list_workspacesList workspaces and their datamarts. Hosted: only the ones you approvedNomcp:datamarts:read
sync_datasourceStart a schema syncYesmcp:datamarts:write
create_datamartPlan or create a datamart from tables and relationships. ConfirmYesmcp:datamarts:write
create_workspaceHosted only. Create a workspace. Needs the All workspaces I can access grant and a role that may create oneYesmcp:datamarts:write

You connect a datasource in the app, not over MCP.

Data apps and tokens

ToolWhat it doesChangesHosted access
list_data_appsList data appsNomcp:dashboards:read
list_tenantsList the client IDs in your tenancy databaseNomcp:dashboards:read
create_data_appCreate a data appYesmcp:embeds:write
list_api_tokensList a data app’s API tokensNomcp:embeds:write
create_api_tokenCreate and activate an API tokenYesmcp:embeds:write
rotate_api_tokenRotate an API tokenYesmcp:embeds:write

Embeds

ToolWhat it doesChangesHosted access
create_embedCreate an embed, standard or per client with clientIdYesmcp:embeds:write
list_embedsList embedsNomcp:dashboards:read
get_embed_detailsRead one embedNomcp:dashboards:read
update_embedChange access settings, options, filters and translationsYesmcp:embeds:write
customize_embed_themeApply a theme preset, colors, fonts, cards and chart stylesYesmcp:embeds:write
get_demo_linkGet the demo link for one client, the same link as Share Demo Link in the appYesmcp:embeds:write
generate_guest_tokenCreate a guest token for your frontend (server side)Yesmcp:embeds:write
generate_embed_codeWrite integration code for React, Next.js, Vue, Angular, Svelte, SolidJS or plain JavaScriptNomcp:dashboards:read

Dashboards

ToolWhat it doesChangesHosted access
list_dashboardsList dashboards by data app, workspace or allNomcp:dashboards:read
get_dashboardRead a dashboard and its metricsNomcp:dashboards:read
create_dashboardCreate a workspace dashboard from a list of tilesYesmcp:dashboards:write
generate_dashboard_tilesHave AI draft tiles for a dashboardYesmcp:dashboards:write, mcp:query, mcp:embeds:write
dashboard_snapshotA PNG of a dashboard or one chart, as the signed-in user sees it. Needs the hosted connectorYesmcp:dashboards:read
list_scheduled_reportsList scheduled reports for a dashboard or clientNomcp: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.

ToolWhat it doesChanges
list_dashboard_releasesList a dashboard’s releases, newest first, with edits made since the last oneNo
stage_dashboard_releaseAlways a dry run. Shows what changes and returns the expected_versionNo
publish_dashboard_releasePublish the reviewed release in the next environment. Same dashboard ID and embeds. ConfirmYes
rollback_dashboard_releaseGo back to an earlier release. ConfirmYes

Questions and charts

ToolWhat it doesChangesHosted access
ask_questionTurn a question into SQL, run it and return rows with a chartNomcp:query
render_metric_tileDraw a saved metric as a chart or KPI, with no embed or data app. Pass clientId to read it as one clientNomcp:dashboards:read, mcp:query
preview_chartRedraw an ask_question answer as another chart type. No query runsNomcp:query
save_chart_as_dashboardSave an ask_question answer as a workspace metric on a new dashboard. ConfirmYesmcp: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

ToolWhat it doesChangesHosted access
list_widgetsList the widgets on a dashboard. With clientId, the widgets one client seesNomcp:dashboards:read
validate_metric_specCheck a SQL metric against its dashboard and datasource without savingYesmcp:dashboards:read, mcp:query, mcp:embeds:write
create_or_update_metric_from_queryPlan or save a SQL metric on a client dashboard. ConfirmYesmcp:dashboards:write, mcp:query, mcp:embeds:write
create_workspace_metricPlan or save an unpublished workspace metric (no client). ConfirmYesmcp:dashboards:write, mcp:query
add_widgetAdd a widget: copy a template metric, send a metric config, or save a generated draftYesmcp:dashboards:write, mcp:embeds:write
update_widgetChange a widget’s name, SQL, chart settings or publish stateYesmcp:dashboards:write, mcp:embeds:write
remove_widgetHide a widget for one client onlyYesmcp:dashboards:write, mcp:embeds:write
generate_widgetHave AI draft a widget from a prompt. Pass the draft to add_widget to save itYesmcp: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:

ResultWhat it means
BlockedThe 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 skippedThe 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_widget refuses a metricId that is used twice in one call, or that already exists, and nothing is saved. create_or_update_metric_from_query accepts an existing metricId and updates that widget in place when conflictStrategy is update. 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_widget refuses a chart that uses a saved semantic plan (SEMANTIC_WIDGET_NOT_SUPPORTED). Send it as SQL, or create it in Databrain.
  • update_widget checks 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, and update_widget answers NO_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:

FieldValue
details.objectThe missing object, when there is one: kind (table, column, schema, database, function, or object) and name. A syntax error has no object.
details.positionThe line and column in the SQL you sent, and a source. It can be missing.
details.errorCodeA DBN-QRY-* code. See Error codes.
details.refA 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

ToolWhat it doesChangesHosted access
get_semantic_layerRead table and column descriptions, synonyms and the completion scoreNomcp:datamarts:read
update_semantic_layerAdd descriptions, synonyms and example questionsYesmcp:datamarts:write
start_semantic_layer_generationStart AI generation of descriptions for a datamartYesmcp:datamarts:write
get_semantic_layer_generation_statusCheck generation progressNomcp:datamarts:read
search_semantic_modelFind the model entities that match a questionNomcp:datamarts:read
get_semantic_entityRead one entity and its current content hashNomcp:datamarts:read
propose_semantic_changeCheck a full YAML source, a YAML patch or one change, and return the plan. Writes nothingNomcp:datamarts:read
eval_semantic_modelCheck model test questions. Runs no SQLNomcp:datamarts:read, mcp:query
apply_semantic_changePreview by default. Applies live with the reviewed hash. ConfirmYesmcp:datamarts:write
semantic_model_draftStart or resume a saved authoring draft, choose Auto or Review, accept proposals, Undo, and run checks. Hosted onlyYesmcp: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.

ToolWhat it doesHosted access
ask_bryn_metricAsk or plan a metric in a workspace. Does not save itmcp:query
ask_bryn_semantic_modelAsk or plan with the semantic model Brynmcp:datamarts:read, mcp:datamarts:write
ask_bryn_themeAsk, plan or build a theme draft. Does not save the thememcp:embeds:write
ask_bryn_custom_chartAsk, plan or build a custom chart draft. Saves and publishes nothingmcp: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

ToolWhat it doesChangesHosted access
custom_chart_scaffoldReturn the files of a new chart project. Writes nothingNomcp:custom-charts:read
custom_chart_editChange a chart draft with Bryn. Never saves or publishesYesmcp:custom-charts:write
custom_chart_previewBuild a draft in memory and preview it with sample rowsNomcp:custom-charts:read
custom_chart_validateCheck a manifest and bundle. Never savesNomcp:custom-charts:read
custom_chart_uploadUpload a built bundle as a private chart or a new version. ConfirmYesmcp:custom-charts:write
list_custom_chartsList your company’s custom chart typesNomcp:custom-charts:read
publish_custom_chartPublish a version so every builder can use it. ConfirmYesmcp: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.