Skip to main content

​
Common Issues

Cause: Neither DATABRAIN_SERVICE_TOKEN nor DATABRAIN_API_TOKEN is set, or your MCP client is not reading the configured env block.Fix:
  1. Check that your token is in the env block of your MCP config.
  2. Verify the token value has no extra spaces or quotes.
  3. Restart your AI client after changing the config.
{
  "mcpServers": {
    "databrain": {
      "command": "npx",
      "args": ["@databrainhq/mcp-server"],
      "env": {
        "DATABRAIN_SERVICE_TOKEN": "your-actual-token-here"
      }
    }
  }
}
If the token is set correctly and the error persists, regenerate it in Settings -> Service Tokens in the Databrain UI.
Cause: You configured only DATABRAIN_API_TOKEN. API tokens are scoped to one data app and cannot run org-level setup tools.Fix: Add DATABRAIN_SERVICE_TOKEN when you need discovery, data app management, API token creation, semantic layer operations, or datamart setup.API-token-only mode is still valid for embed operations, widget operations, guest tokens, demo links, and scheduled report metadata inside the configured data app.
Cause: No workspace was selected, the selected workspace has no dashboards, or the configured token is scoped too narrowly.Fix: Ask the assistant:
“List my workspaces and then show dashboards”
Dashboards are usually scoped to workspaces. If you see workspaces but no dashboards, verify that dashboards exist in the Databrain UI for that workspace.
Cause: Usually a token, ID, domain, or guest token payload mismatch.Fix:
  1. Guest token generated server-side? Never expose API tokens in frontend code.
  2. IDs match? Verify the embed ID and dashboard ID.
  3. Domain whitelisted? Check that your frontend’s domain is allowed in the data app settings.
  4. Inspect the embed: Ask the assistant:
“Check my embed configuration for issues”
The assistant uses get_embed_details to inspect access settings, dashboard references, and token inputs.
Cause: Existing guest tokens may still carry old configuration.Fix: After updating theme or options through customize_embed_theme or update_embed:
  1. Regenerate the guest token with generate_guest_token.
  2. Reload your application to use the new token.
Guest tokens are generated server-side and should be refreshed after configuration changes that affect runtime behavior.
Cause: The widget may be unpublished, the preview is using a stale guest token, or the wrong clientId was used.Fix:
  1. Ask the assistant to call list_widgets for the target clientId and dashboard.
  2. Confirm the widget has isPublished: true if it should appear to end users.
  3. Generate a fresh get_demo_link URL.
  4. If testing inside your own app, regenerate the app’s guest token.
Cause: Production writes require an explicit confirmation value.Fix: Run the dry-run first, review the returned plan, then apply only after approval:
{
  "mode": "apply",
  "confirm": "APPLY_TO_PRODUCTION"
}
This applies to create_or_update_metric_from_query and production datamart creation through create_datamart.
Cause: The semantic layer is empty, incomplete, or missing business context.Fix: Check its status:
“Check the semantic layer quality for my datamart”
If descriptions or synonyms are missing, ask:
“Add descriptions and synonyms to improve query accuracy”
The assistant can update metadata with update_semantic_layer or start semantic-layer generation with start_semantic_layer_generation.
Cause: Usually a Node.js version issue or invalid environment variable.Fix: The MCP server requires Node.js 18 or higher:
node --version
If you see a version below 18, update Node.js. Also verify DATABRAIN_API_URL and DATABRAIN_DEMO_DOMAIN are valid URLs when set.
Cause: npm/npx is not installed or the client cannot fetch the package.Fix:
  1. Ensure npm is installed: npm --version
  2. Try running the package directly:
npx @databrainhq/mcp-server
  1. If fetching the package hangs, install globally:
npm install -g @databrainhq/mcp-server
Then update your config to use the global binary:
{
  "mcpServers": {
    "databrain": {
      "command": "databrain-mcp-server",
      "env": {
        "DATABRAIN_SERVICE_TOKEN": "<your-service-token>"
      }
    }
  }
}

​
Diagnostics

Ask your assistant:
“Who am I authenticated as in Databrain?”
This calls whoami and confirms whether the session is using a service token or API token. For embed issues, ask:
“Check my embed configuration for issues”
The assistant uses get_embed_details to inspect access settings and dashboard references, then regenerates a guest token if runtime state changed. For customer dashboard issues, ask:
“List widgets for this client and give me a demo link”
The assistant uses list_widgets and get_demo_link.

​
Known Limitations

AreaLimitationWorkaround
Datasource setupDatasources are connected in the Databrain UICreate datasources in the Databrain UI, then use list_datasources, discover_datasource_schema, and sync_datasource
Workspace setupWorkspaces are created in the Databrain UICreate workspaces in the Databrain UI, then use list_workspaces and dashboard workflows
Transportstdio only; no HTTP/SSE transport yetUse npx with your MCP client’s config file
Production writesDatamart and SQL-to-metric apply operations require explicit confirmationRun dry-run first, review the plan, then apply with confirm: "APPLY_TO_PRODUCTION"
Scheduled reportslist_scheduled_reports returns configured schedule metadataUse Databrain reporting views for delivery status

​
Getting Help

Quickstart

Start over with setup

Client Setup

Verify your client config

Tools Reference

Review available tools