Skip to Content

MCP Server

Fix MCP problems

Find why an AI app cannot connect to Databrain or a tool call fails, and fix it.

See what the AI app did

Go to Settings > Diagnostics, open Logs and pick the MCP view. It lists every MCP tool call with its result: OK, Error or Denied. Filter by Time range and Result, or search for a tool. Select a call to see its session.

Diagnostics needs the right plan and permission. Without it, ask the AI app to repeat the call and read the error.

Connecting and signing in

Settings > MCP says “Sign-in for AI apps is turned off on this Databrain install”. The hosted connector is off on your self-hosted instance. Ask your admin to turn on the MCP server, or use the local server with a service token.

“Your role does not allow connecting AI apps”. Ask an Admin to turn on MCP > Connect for your role in Settings > People & Access > Roles.

“Your role cannot give this access”. Your role in the chosen workspaces allows none of the access the app asked for. Choose other workspaces, or ask an Admin for a role that can.

“This sign-in link has expired”. A link works for a few minutes and only once. Start the connection again from the AI app.

“Finish in the browser that started this”. Start again from the AI app and finish in the same browser. On a self-hosted instance with the app and the API on different domains, ask your admin to put them on one site.

“Too many connection attempts”. Wait a minute, then start the connection again from the app.

“Your workspaces changed”. You lost access to a workspace you picked. Connect again and pick again.

A running chat stops with a sign-in error. Someone revoked the connection, or it expired. Connect the app again. See Manage AI app connections.

Tool calls

A tool answers insufficient_scope. The app did not get the access this tool needs. Connect again and approve it. The tools reference lists the access for each tool.

“Hosted authorization denied this tool call”. Your role, the workspace or the client is not allowed for this call. Check your role in that workspace.

WORKSPACE_REQUIRED: “Name the workspace for this call”. You approved more than one workspace. Tell the app which workspace to use. whoami lists the ones you approved.

A tool is missing. Dashboard release tools exist only on the local server. create_workspace, dashboard_snapshot and the Bryn tools exist only on the hosted connector. Bryn tools also need Bryn on your plan.

“Too many MCP control-plane requests, please try later”. The server allows 30 requests a minute for each token or user. Wait a minute and try again.

Local server

MISSING_SERVICE_TOKEN or the server does not start. Put DATABRAIN_SERVICE_TOKEN in the env block of the client config and restart the client. Check that Node.js is version 20 or later with node --version.

MISSING_API_TOKEN. This is normal on first setup. Ask the app to create an API token for your data app.

The token is refused. A token works only on the instance that made it. On self-hosted, set DATABRAIN_API_URL to your API address. Test the token in Settings > MCP > Show service token setup > Test connection.

No dashboards found. Dashboards belong to workspaces. Ask the app to list your workspaces first, then the dashboards.

Embeds made with MCP

The embed does not show in your app. Make the guest token on your server, never in the browser. Check that the embed ID and dashboard ID match. Ask the app to check the embed with get_embed_details.

A theme change does not show. Guest tokens made before the change keep the old look. Make a new guest token or reload your app.

Saving SQL, widgets and metrics

A save fails with a SQL error. add_widget, update_widget, create_or_update_metric_from_query, or create_workspace_metric found a table or column in your SQL that the datasource does not have, or a syntax error. Nothing was saved.

  1. Read the message and the hint first.
  2. If details.object is present, it names the table or column. If details.position is present, it gives the line and column. Check source: engine is exact, search is the first match of the name. A syntax error can have neither.
  3. Compare the name with discover_datasource_schema.
  4. Correct the SQL and send it again.

For a batch, the error says which widget to fix. If you see DBN-QRY-* and a ref, give both to support.

Widget saved with “SQL not checked”. The check could not run on the Databrain side, or you use an older self-hosted backend. The widget is saved. Open the widget in the dashboard and confirm it loads. If the SQL has {{variables}}, the check is skipped by design.

A save says “unknown”. The request was sent, but the answer did not come back (a timeout or a lost connection). The widget may be saved.

  • New widget: call list_widgets and look for it. Send it again only if it is not there.
  • Edit: list_widgets shows the name and publish state, not the SQL or chart settings. Open the widget in Databrain and check the fields you changed. Until you do, treat the edit as unconfirmed. If the old widget is still there, that does not mean the edit failed or succeeded.

update_widget answers NO_TENANT_SCOPE. The data app of your API token has no tenant setup, so widgets saved with it have no owner and cannot be edited with it. Edit the widget in Databrain, or set up tenancy for the data app. list_widgets shows editable: false for these widgets.

A write returns a plan and saves nothing. The tool needs confirm: "APPLY_TO_PRODUCTION". Read the plan, then give the value to the app yourself.

A semantic change stops with a conflict. Someone changed the model after the plan was made. Ask the app to propose the change again, review it, then apply.

Self-hosted MCP server

/mcp answers 503 mcp_unavailable. The MCP server container is not running. See Self-hosted configuration.

403 invalid_host. Your load balancer changed the Host header. Forward the original Host header to the MCP server.

Ask for help

Send support the tool name, the time, the error message and any ref or DBN- code. Do not send tokens or customer data. Error codes: DBN-MCP-301, DBN-MCP-302.