> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usedatabrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Add embedded analytics to your app using natural language. Connect the Databrain MCP server to any AI assistant and describe what you want.

<Note>
  `@databrainhq/mcp-server` is available on [npm](https://www.npmjs.com/package/@databrainhq/mcp-server) and requires Node.js 18+.
</Note>

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](https://modelcontextprotocol.io) (MCP), an open standard that connects AI assistants to external tools and data sources.

***

## How It Works

<Steps>
  <Step title="You describe what you want" icon="comment">
    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.
  </Step>

  <Step title="MCP server translates to API calls" icon="wand-magic-sparkles">
    The server maps your request to the right Databrain actions, manages authentication, validates inputs, and applies production safeguards for writes.
  </Step>

  <Step title="Databrain API executes" icon="server">
    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.
  </Step>
</Steps>

***

## 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                     |

<Note>
  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`.
</Note>

***

## Key Capabilities

<CardGroup cols={2}>
  <Card title="Embed Dashboards" icon="window-maximize">
    Discover data apps, select dashboards, create embeds, and generate framework-specific frontend code through conversation.
  </Card>

  <Card title="Tenant Discovery" icon="users">
    List valid `clientId` values from your tenancy database before creating guest tokens or editing customer dashboards.
  </Card>

  <Card title="Query Your Data" icon="magnifying-glass-chart">
    Ask questions in natural language. The AI converts them to SQL, runs the query, and returns results with chart suggestions.
  </Card>

  <Card title="Customer Dashboard Widgets" icon="chart-line">
    List, add, update, remove, or generate widgets for a specific customer's dashboard without changing other customers.
  </Card>

  <Card title="SQL to Metrics" icon="code">
    Validate warehouse-tested SQL, dry-run Databrain metric writes, and apply only after explicit production confirmation.
  </Card>

  <Card title="Workspace Metrics" icon="square-plus">
    Create unpublished, unattached workspace-level metrics from validated SQL before deciding where to publish them.
  </Card>

  <Card title="Brand & Theme" icon="palette">
    Customize colors, fonts, chart styles, responsive breakpoints, card styling, and access presets.
  </Card>

  <Card title="Self-Serve & Access" icon="sliders">
    Enable drag-and-drop or chat metric creation, configure filters, localize embeds, and lock down permissions.
  </Card>

  <Card title="Semantic Layer" icon="layer-group">
    Populate, maintain, and auto-generate table/column descriptions to improve natural language query accuracy.
  </Card>
</CardGroup>

***

## 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**.

| Component                                               | Count | Purpose                                                                                                                  |
| ------------------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------ |
| [Tools](/developer-docs/mcp-server/tools-reference)     | 36    | API operations for discovery, tenants, embeds, widgets, workspace metrics, semantic layer, metric migration, and reports |
| [Prompts](/developer-docs/mcp-server/prompts-reference) | 7     | Guided workflows for common setup and production-safe maintenance tasks                                                  |
| Knowledge Resources                                     | 11    | Built-in references the AI consults automatically                                                                        |

<Note>
  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.
</Note>

### Built-in Knowledge Resources

The server bundles reference documentation that your AI assistant reads automatically when needed.

<AccordionGroup>
  <Accordion title="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        |
  </Accordion>
</AccordionGroup>

***

## 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.

<Warning>
  Production write tools default to dry-run where supported and require explicit confirmation before applying changes.
</Warning>

***

## Get Started

<CardGroup cols={3}>
  <Card title="Quickstart" icon="bolt" href="/developer-docs/mcp-server/quickstart">
    Set up in 2 minutes
  </Card>

  <Card title="Workflows" icon="route" href="/developer-docs/mcp-server/workflows">
    Common use cases
  </Card>

  <Card title="Tools Reference" icon="wrench" href="/developer-docs/mcp-server/tools-reference">
    All 36 tools
  </Card>
</CardGroup>