MCP Server

@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 Server	NPM Plugin (`@databrainhq/plugin`)
Best for	Setting up and configuring embeds via AI assistant	Rendering embeds in your frontend
How it works	Natural language in Codex, Cursor, Claude, Windsurf, or any MCP client	Web components (`<dbn-dashboard>`, `<dbn-metric>`)
What it does	Creates embeds, discovers tenants, manages tokens, configures themes/filters, queries data, edits widgets, enables self-serve analytics, generates frontend code	Renders dashboards and metrics in the browser
When you use it	During development, setup, and ongoing embed maintenance	At 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, 8 guided prompts, and 11 built-in knowledge resources.

Component	Count	Purpose
Tools	36	API operations for discovery, tenants, embeds, widgets, workspace metrics, semantic layer, metric migration, and reports
Prompts	8	Guided workflows for common setup and production-safe maintenance tasks
Knowledge Resources	11	Built-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 or updated only after the same explicit confirmation. Re-applying with the same metricId updates the metric in place and re-hydrates Dimensions/Measures from the new SQL. 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.

View all 11 resources

Resource	Content
Getting Started	Entity model, onboarding checklist, token types
API Reference	Key Databrain API endpoints and examples
Embedding Guide	Framework-specific code for React, Next.js, Vue, Angular, Svelte, SolidJS, and vanilla JS
Theme Reference	Admin theme, component theme, and chart appearance schemas
Web Component Reference	`<dbn-dashboard>` and `<dbn-metric>` attributes
Filter Reference	Filter types, operators, runtime filters, and dashboard filters
Self-Serve Reference	Permission flags and metric creation modes
Semantic Layer Guide	Semantic layer setup for AI-powered querying
Multi-Tenancy Guide	Row-level security, `clientId` patterns, and tenant isolation
Use Case Guides	Tool sequences and decision guidance for common flows
Permission Schema	Embed `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.

Variable	Required	Default	Description
`DATABRAIN_SERVICE_TOKEN`	One 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_TOKEN`	One of two	-	Per-data-app token. Created automatically during setup via `create_api_token`, or provided manually for a single data app.
`DATABRAIN_API_URL`	Required for self-hosted	`https://api.usedatabrain.com`	API origin for cloud or self-hosted Databrain.
`DATABRAIN_DEMO_DOMAIN`	No	`https://demo.usedatabrain.com`	Base 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

Embedding Setup

Framework Integration

Component Options

Authentication & Security

Filtering & Personalization

Customization

Events & Interactions

End-User Features

AI Chat Mode

Self-Hosted Deployment

Solution Patterns

Testing & Debugging

Migration & Legacy

Additional Resources

MCP Server

How It Works

MCP Server vs NPM Plugin

Key Capabilities

Embed Dashboards

Tenant Discovery

Query Your Data

Customer Dashboard Widgets

SQL to Metrics

Workspace Metrics

Brand & Theme

Self-Serve & Access

Semantic Layer

Supported AI Clients

What’s Included

Built-in Knowledge Resources

Environment Variables

Authentication Model

Get Started

Quickstart

Workflows

Tools Reference

​How It Works

​MCP Server vs NPM Plugin

​Key Capabilities

Embed Dashboards

Tenant Discovery

Query Your Data

Customer Dashboard Widgets

SQL to Metrics

Workspace Metrics

Brand & Theme

Self-Serve & Access

Semantic Layer

​Supported AI Clients

​What’s Included

​Built-in Knowledge Resources

​Environment Variables

​Authentication Model

​Get Started

Quickstart

Workflows

Tools Reference

How It Works

MCP Server vs NPM Plugin

Key Capabilities

Supported AI Clients

What’s Included

Built-in Knowledge Resources

Environment Variables

Authentication Model

Get Started