Skip to main content
@databrainhq/mcp-server is available on npm and requires Node.js 18+.
The Databrain MCP server lets you manage embedded analytics through your AI assistant. Instead of navigating the Databrain UI or calling REST APIs directly, describe what you want in plain English and the assistant handles the setup steps for you. 
"Embed my sales dashboard in my React app"
"Find valid client IDs for my workspace"
"Add a widget to a customer's dashboard"
"Dry-run this SQL as a Databrain metric"
"Enable self-serve metric creation on this embed"
"What was total revenue last month?"
The server implements the Model Context Protocol (MCP), an open standard that connects AI assistants to external tools and data sources.

​
How It Works

You describe what you want

Tell your AI assistant what you need: embed a dashboard, find valid tenants, query data, customize theming, add customer-specific widgets, migrate SQL into a metric, enable self-serve analytics, or review scheduled report configuration.

MCP server translates to API calls

The server maps your request to the right Databrain actions, manages authentication, validates inputs, and applies production safeguards for writes.

Databrain API executes

Your data apps, dashboards, embeds, tenants, widgets, workspace metrics, semantic layer, and scheduled report metadata are accessed through the Databrain API. Results flow back through the server to your assistant.

​
MCP Server vs NPM Plugin

Databrain offers two integration paths. Choose based on your workflow:
MCP ServerNPM Plugin (@databrainhq/plugin)
Best forSetting up and configuring embeds via AI assistantRendering embeds in your frontend
How it worksNatural language in Codex, Cursor, Claude, Windsurf, or any MCP clientWeb components (<dbn-dashboard>, <dbn-metric>)
What it doesCreates embeds, discovers tenants, manages tokens, configures themes/filters, queries data, edits widgets, enables self-serve analytics, generates frontend codeRenders dashboards and metrics in the browser
When you use itDuring development, setup, and ongoing embed maintenanceAt runtime in your application
They’re complementary, not competing. Use the MCP server to set up and maintain your embeds, then use the NPM plugin to render them in your app. The MCP server can generate plugin code via generate_embed_code.

​
Key Capabilities

Embed Dashboards

Discover data apps, select dashboards, create embeds, and generate framework-specific frontend code through conversation.

Tenant Discovery

List valid clientId values from your tenancy database before creating guest tokens or editing customer dashboards.

Query Your Data

Ask questions in natural language. The AI converts them to SQL, runs the query, and returns results with chart suggestions.

Customer Dashboard Widgets

List, add, update, remove, or generate widgets for a specific customer’s dashboard without changing other customers.

SQL to Metrics

Validate warehouse-tested SQL, dry-run Databrain metric writes, and apply only after explicit production confirmation.

Workspace Metrics

Create unpublished, unattached workspace-level metrics from validated SQL before deciding where to publish them.

Brand & Theme

Customize colors, fonts, chart styles, responsive breakpoints, card styling, and access presets.

Self-Serve & Access

Enable drag-and-drop or chat metric creation, configure filters, localize embeds, and lock down permissions.

Semantic Layer

Populate, maintain, and auto-generate table/column descriptions to improve natural language query accuracy.

​
Supported AI Clients

The server uses stdio transport and works with any MCP-compatible client:
  • Codex - OpenAI’s coding agent CLI
  • Cursor - IDE with built-in MCP support
  • Claude Desktop - Anthropic’s desktop app
  • Claude Code - CLI tool for developers
  • Windsurf - Codeium’s AI IDE
  • Any MCP client - Any tool that supports the Model Context Protocol

​
What’s Included

The server ships with 36 tools, 7 guided prompts, and 11 built-in knowledge resources.
ComponentCountPurpose
Tools36API operations for discovery, tenants, embeds, widgets, workspace metrics, semantic layer, metric migration, and reports
Prompts7Guided workflows for common setup and production-safe maintenance tasks
Knowledge Resources11Built-in references the AI consults automatically
Datasource and workspace setup still happen in the Databrain UI. Datamarts can be planned with create_datamart in dry_run mode and created only with confirm: "APPLY_TO_PRODUCTION". Workspace-level metrics can be planned with create_workspace_metric in dry_run mode and created only after the same explicit confirmation. The semantic layer is populated and maintained via MCP tools.

​
Built-in Knowledge Resources

The server bundles reference documentation that your AI assistant reads automatically when needed.
ResourceContent
Getting StartedEntity model, onboarding checklist, token types
API ReferenceKey Databrain API endpoints and examples
Embedding GuideFramework-specific code for React, Next.js, Vue, Angular, Svelte, SolidJS, and vanilla JS
Theme ReferenceAdmin theme, component theme, and chart appearance schemas
Web Component Reference<dbn-dashboard> and <dbn-metric> attributes
Filter ReferenceFilter types, operators, runtime filters, and dashboard filters
Self-Serve ReferencePermission flags and metric creation modes
Semantic Layer GuideSemantic layer setup for AI-powered querying
Multi-Tenancy GuideRow-level security, clientId patterns, and tenant isolation
Use Case GuidesTool sequences and decision guidance for common flows
Permission SchemaEmbed accessSettings, guest token permissions, precedence rules, and limitations

​
Environment Variables

At least one credential is required. Use a service token for full setup and management flows; use an API token only when you are operating inside one data app.
VariableRequiredDefaultDescription
DATABRAIN_SERVICE_TOKENOne of two-Org-level token from Settings -> Service Tokens. Powers discovery, tenant lookup, setup, data app management, semantic layer, and production-safe datamart and workspace-metric operations.
DATABRAIN_API_TOKENOne of two-Per-data-app token. Created automatically during setup via create_api_token, or provided manually for a single data app.
DATABRAIN_API_URLRequired for self-hostedhttps://api.usedatabrain.comAPI origin for cloud or self-hosted Databrain.
DATABRAIN_DEMO_DOMAINNohttps://demo.usedatabrain.comBase URL used by get_demo_link for hosted dashboard previews.

​
Authentication Model

Databrain uses two token types: Service Token - org-level, set once in your MCP config. Used for datasource/datamart/workspace discovery, tenant lookup, data app and API token management, dashboard listing, semantic layer operations, natural language querying, create_datamart, and create_workspace_metric. API Token - scoped to a single data app. Used for embed operations, guest token generation, widget operations, data-app-scoped dashboard listing, and scheduled report metadata. The MCP server can create and activate API tokens via create_api_token when a service token is configured.
Production write tools default to dry-run where supported and require explicit confirmation before applying changes.

​
Get Started

Quickstart

Set up in 2 minutes

Workflows

Common use cases

Tools Reference

All 36 tools