Skip to main content
@databrainhq/mcp-server v0.2.0 — available on npm. 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 rest. 
"Embed my sales dashboard in my React app"
"What was total revenue last month?"
"Brand my embed to match our company colors"
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, query data, customize theming, or anything else.

MCP server translates to API calls

The server (@databrainhq/mcp-server) maps your request to the right Databrain API operations, manages authentication, and validates inputs.

Databrain API executes

Your data, dashboards, and embeds are accessed via the Databrain API. Results flow back through the server to your assistant.
All tokens are managed automatically. You provide your service token once in the config — everything else is created and handled by the server during setup.

​
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 Cursor, Claude, WindsurfWeb components (<dbn-dashboard>, <dbn-metric>)
What it doesCreates embeds, manages tokens, configures themes/filters, queries data, generates frontend codeRenders dashboards and metrics in the browser
When you use itDuring development and setupAt runtime in your application
They’re complementary, not competing. Use the MCP server to set up and configure your embeds, then use the NPM plugin to render them in your app. The MCP server even generates the plugin code for you via generate_embed_code.

​
Key Capabilities

Embed Dashboards

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

Query Your Data

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

Brand & Theme

Customize colors, fonts, chart styles, responsive breakpoints, and card styling to match your product.

Multi-Tenant Embeds

Create per-client dashboard embeds with row-level security. Each customer sees only their data.

Self-Serve Analytics

Enable end-users to build their own metrics with drag-and-drop or AI-powered chat mode.

Semantic Layer

Populate and maintain table/column descriptions, synonyms, and example questions to improve natural language query accuracy.

​
Supported AI Clients

The server uses stdio transport and works with any MCP-compatible client:
  • 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 24 tools, 10 guided prompts, and 11 built-in knowledge resources.
ComponentCountPurpose
Tools24API operations — list, create, update, configure
Prompts10Guided workflows for common tasks
Knowledge Resources11Built-in references the AI consults automatically
Infrastructure creation (datasources, datamarts, workspaces) is done in the Databrain UI. The MCP server handles everything from embedding onward — plus the semantic layer, which is populated entirely via MCP tools.

​
Built-in Knowledge Resources

The server bundles reference documentation that your AI assistant reads automatically when needed — you don’t have to provide context manually.
ResourceContent
Getting StartedEntity model, onboarding checklist, token types
API ReferenceAll Databrain API endpoints
Embedding GuideFramework-specific code (React, Next.js, Vue, Angular, Svelte, vanilla JS)
Theme ReferenceFull theme schema — admin theme, component theme, chart appearance
Web Component ReferenceAll <dbn-dashboard> and <dbn-metric> attributes
Filter ReferenceFilter types, operators, server-side filters
Self-Serve ReferencePermission flags, metric creation modes
Semantic Layer GuideAI-powered metric creation setup
Multi-Tenancy GuideRow-level security, clientId patterns, tenant isolation
Use Case GuidesDecision guide for choosing the right setup path
Permission SchemaEmbed accessSettings, guest token permissions, precedence rules

​
Environment Variables

VariableRequiredDefaultDescription
DATABRAIN_SERVICE_TOKENYes—Org-level token from Settings → Service Tokens. Powers all discovery and setup operations.
DATABRAIN_API_TOKENNo—Per-data-app token. Created automatically during setup via create_api_token, or set manually if you already have one.
DATABRAIN_API_URLNohttps://api.usedatabrain.comAPI base URL. Only change this for self-hosted Databrain.

​
Authentication Model

Databrain uses two token types: Service Token — org-level, set once in your MCP config. Used for discovery operations: listing datasources, datamarts, workspaces, data apps, and querying data. API Token — scoped to a single data app. Used for embed operations: creating embeds, customizing themes, generating guest tokens. The MCP server creates these automatically via create_api_token during setup — you never need to manage them manually.

​
Get Started

Quickstart

Set up in 2 minutes

Workflows

Common use cases

Tools Reference

All 24 tools