@databrainhq/mcp-server

Add embedded analytics to your app using natural language. Connect this MCP server to any AI assistant and describe what you want — it handles the setup steps for you.

"What was total revenue last month?"
"Embed my sales dashboard in my React app"

Works with Codex, Claude, Cursor, Windsurf, and any MCP-compatible client.

Setup (2 minutes)

1. Get your Service Token

1. Log in to your Databrain instance (cloud or self-hosted)
2. Go to Settings → Service Tokens
3. Create a new token and copy it

2. Add to your AI client

Self-hosted? Also set DATABRAIN_API_URL in the env block — see Self-hosted Databrain below.

Add the MCP server with your service token:

codex mcp add databrain --env DATABRAIN_SERVICE_TOKEN=YOUR_SERVICE_TOKEN -- npx @databrainhq/mcp-server

Verify the server is configured:

codex mcp list

Start a new Codex session after adding the server.

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "databrain": {
      "command": "npx",
      "args": ["@databrainhq/mcp-server"],
      "env": {
        "DATABRAIN_SERVICE_TOKEN": "<your-service-token>"
      }
    }
  }
}

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "databrain": {
      "command": "npx",
      "args": ["@databrainhq/mcp-server"],
      "env": {
        "DATABRAIN_SERVICE_TOKEN": "<your-service-token>"
      }
    }
  }
}

claude mcp add databrain -- npx @databrainhq/mcp-server

Set your token:

export DATABRAIN_SERVICE_TOKEN="<your-service-token>"

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "databrain": {
      "command": "npx",
      "args": ["@databrainhq/mcp-server"],
      "env": {
        "DATABRAIN_SERVICE_TOKEN": "<your-service-token>"
      }
    }
  }
}

The server uses stdio transport. Set environment variables and run:

export DATABRAIN_SERVICE_TOKEN="<your-service-token>"
npx @databrainhq/mcp-server

Self-hosted Databrain

Running Databrain on your own infrastructure? Point the MCP server at your instance by setting DATABRAIN_API_URL alongside your token:

{
  "mcpServers": {
    "databrain": {
      "command": "npx",
      "args": ["@databrainhq/mcp-server"],
      "env": {
        "DATABRAIN_SERVICE_TOKEN": "<your-service-token>",
        "DATABRAIN_API_URL": "https://api.your-databrain.example.com",
        "DATABRAIN_DEMO_DOMAIN": "https://demo.your-databrain.example.com"
      }
    }
  }
}

Checklist:

• DATABRAIN_API_URL must be the API origin for your self-hosted instance (not the dashboard URL). Typically https://api.<your-domain>.
• The token must be minted from that same self-hosted instance — tokens are not portable across instances.
• Use DATABRAIN_SERVICE_TOKEN (Settings → Service Tokens) for org-level access.
• The MCP client process must be able to reach the URL (VPN, firewall, self-signed certs all apply here).
• Scaffolded frontend code (React, Next.js, Vue, etc.) reads the same DATABRAIN_API_URL for server-side guest-token generation, so the variable flows through to your app.

3. Start talking

Open your AI assistant and try any of these:

"Set up a Databrain embed for my dashboard"

"Brand my embed to match our colors"

"What was total revenue last month?"

The assistant walks you through each step interactively — picking your data app, selecting a workspace and dashboard, creating the embed, and generating the frontend code.

What you can ask

Query your data

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

"What was total revenue last month?"

"Show me the monthly revenue trend for the past year"

"Compare sales by region — break it down by quarter"

No setup required beyond your service token. Use list_datamarts to see available data, and the AI handles the rest. Follow-up questions use conversation context for better accuracy.

"Now show only the top 5 regions"

If results seem off, improve the semantic layer — the metadata that helps the AI understand your column names and relationships:

"Check the semantic layer quality for my orders datamart"

"Add descriptions and synonyms to improve query accuracy"

Embed a dashboard

The most common flow. You have dashboards in the Databrain UI and want to embed them.

"Embed my sales dashboard in my React app"

The assistant will: discover your data apps → ensure API token → select workspace → list dashboards → create embed → generate a guest token → give you framework-specific code.

Brand and theme

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

"Make my embed match our brand — primary color #4F46E5, dark mode, Inter font"

"Apply the corporate theme preset and hide the dashboard name"

Multi-tenant embeds

Each of your customers gets their own dashboard with row-level security.

"Create per-client dashboard embeds for my SaaS app"

Tweak widgets on a customer dashboard

Add, remove, or modify widgets (metrics) on a specific customer's embed without opening the Databrain UI. Clone from a template widget, write a fresh SQL spec, or generate one from a prompt. End with a demo link to verify exactly what that customer will see — same URL the UI's "Share Demo Link" generates.

"Add the 'Calls per day' widget from the standard template to a client's dashboard"

"Generate a widget showing disqualification reasons and add it to a client's embed"

"Remove the billing widget from one client's dashboard but keep it for other clients"

"Give me a demo link for a client's dashboard so I can see what they'll see"

Migrate validated SQL into metrics

Turn warehouse-validated SQL into Databrain metrics with a production-safe flow: validate the target dashboard/datasource, produce a dry-run plan, then apply only after explicit confirmation.

"Validate this SQL as a new metric on my operations dashboard"

"Dry-run creating this converted query as a metric, then show me the exact apply plan"

Enable self-serve analytics

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

"Enable metric creation on my embed with the visual builder"

Filters, localization, permissions

"Add a date range filter and a region dropdown to my dashboard"

"Set up French translations for my embed"

"Lock down the embed so users can only view, not edit"

Environment Variables

At least one of DATABRAIN_SERVICE_TOKEN or DATABRAIN_API_TOKEN must be set. 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, setup, data app management, semantic layer, and production-safe datamart operations. | | DATABRAIN_API_TOKEN | One of two† | — | Per-data-app token. Created automatically during setup via create_api_token, or set manually if you already have one. Sufficient for embedding operations on a single data app. | | DATABRAIN_API_URL | Required for self-hosted | https://api.usedatabrain.com | API base URL. Set to your instance's API origin (e.g. https://api.your-databrain.example.com). | | DATABRAIN_DEMO_DOMAIN | Optional | https://demo.usedatabrain.com | Base host for get_demo_link URLs. Override for self-hosted instances or custom preview domains (e.g. https://demo.your-databrain.example.com). |

† At least one of these two credentials must be set. Token resolution priority: DATABRAIN_SERVICE_TOKEN > DATABRAIN_API_TOKEN.

Available Prompts

Prompts are guided workflows your AI assistant can follow. Ask for them by name or describe what you want.

| Prompt | What it does | |--------|-------------| | embed-existing-dashboard | Embed a dashboard you've already built in the Databrain UI | | embed-blank-dashboard | Multi-tenant setup — each client gets their own dashboard | | customize-customer-dashboard | Add, modify, or remove widgets on a specific customer's embed — per-client scope | | brand-my-embed | Customize colors, fonts, charts, card styling, responsive layout | | query-data | Query your data with natural language, manage the semantic layer | | populate-semantic-layer | Auto-generate table/column descriptions to enable natural language querying | | sql-to-metric-migration | Production-safe SQL-to-metric workflow: validate, dry-run, then apply with explicit confirmation |

Tools Reference

35 tools organized by category. Your AI assistant picks the right tools automatically — you don't need to call them directly.

Note: Datasource and workspace creation happen outside MCP. Datamarts can be planned with create_datamart in dry_run mode and created only with confirm: "APPLY_TO_PRODUCTION". The semantic layer is managed via MCP tools (get_semantic_layer, update_semantic_layer, start_semantic_layer_generation, get_semantic_layer_generation_status).

| Tool | Description | |------|-------------| | list_datasources | List connected datasources | | discover_datasource_schema | Inspect a datasource to see available tables and columns | | list_datamarts | List datamarts | | list_workspaces | List all workspaces (shows datamart/datasource connections) | | sync_datasource | Trigger datasource schema sync | | create_datamart | Dry-run or create a datamart from selected tables and relationships |

| Tool | Description | |------|-------------| | list_data_apps | List data apps | | list_tenants | List available tenants/clients from the tenancy database | | create_data_app | Create a new data app | | list_api_tokens | List API tokens for a data app | | create_api_token | Create and activate an API token | | rotate_api_token | Rotate an existing API token |

| Tool | Description | |------|-------------| | create_embed | Create an embed (standard or multi-tenant with clientId) | | list_embeds | List embed configurations | | get_embed_details | Get full embed details by ID | | update_embed | Update embed config — access settings, options, filters, i18n, and advanced embed options | | customize_embed_theme | Presets, colors, fonts, cards, chart appearance, responsive layout | | get_demo_link | Get a shareable demo URL for a clientId — same link the UI's "Share Demo Link" generates |

| Tool | Description | |------|-------------| | generate_guest_token | Generate a frontend guest token (server-side) | | generate_embed_code | Generate integration code (React, Next.js, Vue, Angular, Svelte, SolidJS, vanilla JS) |

| Tool | Description | |------|-------------| | ask_question | Ask a natural language question — gets converted to SQL, returns data + chart suggestion | | get_semantic_layer | Inspect semantic layer metadata (table/column descriptions, synonyms, completion score) | | update_semantic_layer | Improve semantic layer quality (add descriptions, synonyms, example questions) | | start_semantic_layer_generation | Start semantic-layer generation for a datamart | | get_semantic_layer_generation_status | Check semantic-layer generation progress |

| Tool | Description | |------|-------------| | list_dashboards | List dashboards (by data app, workspace, or globally) | | list_widgets | List widgets on an embed for a specific client | | validate_metric_spec | Validate a SQL-backed metric target without saving | | create_or_update_metric_from_query | Dry-run or apply a SQL-backed metric create/update | | add_widget | Add a widget — clone from a template (templateMetricId), supply a metric configuration, or use a generated draft | | update_widget | Patch a widget's fields (name, query, chartOptions, isPublished, etc.) | | remove_widget | Per-client soft delete — hides the widget for one client only | | generate_widget | AI-generate a widget draft from a natural-language prompt. Returns a draft; pass to add_widget to persist |

Use list_tenants to discover valid clientId values from the tenancy database. Provide clientId and dashboardName; include workspaceName only if dashboard names are ambiguous. The tools resolve the required resources automatically and refuse to mutate dashboards that are not tenant-scoped for that clientId. Production writes through create_or_update_metric_from_query default to dry_run; apply requires confirm: "APPLY_TO_PRODUCTION".

| Tool | Description | |------|-------------| | list_scheduled_reports | List configured scheduled reports for a dashboard/client scope |

Built-in Knowledge

The server includes 11 reference guides that your AI assistant can consult automatically:

| Resource | Content | |----------|---------| | Getting Started | Entity model, onboarding checklist, token types | | API Reference | All Databrain API endpoints | | Embedding Guide | Framework-specific code (React, Next.js, Vue, Angular, Svelte, vanilla JS) | | Theme Reference | Full theme schema — admin theme, component theme, chart appearance | | Web Component Reference | All <dbn-dashboard> and <dbn-metric> attributes | | Filter Reference | Filter types, operators, server-side filters | | Self-Serve Reference | Permission flags, metric creation modes | | Semantic Layer Guide | AI-powered metric creation setup | | Multi-Tenancy Guide | Row-level security, clientId patterns, tenant isolation | | Use Case Guides | Decision guide for choosing the right setup path | | Permission Schema | Embed accessSettings, guest token permissions, precedence rules |

Troubleshooting

"MISSING_SERVICE_TOKEN" error

Your service token isn't set. Check that DATABRAIN_SERVICE_TOKEN is in your MCP config's env block and restart your AI client.

"MISSING_API_TOKEN" error

This is normal during first-time setup. The assistant will automatically create one via create_api_token. If it persists, ask: "Create an API token for my data app".

No dashboards found

This usually means no workspace was selected. Ask the assistant: "List my workspaces and then show dashboards". Dashboards are scoped to workspaces.

Embed not rendering in frontend

1. Check that the guest token is generated server-side (never expose API tokens in frontend code)
2. Verify the embed ID and dashboard ID match
3. Ask: "Check my embed configuration for issues" — the assistant inspects via get_embed_details

Theme changes not showing

After updating theme or options, existing guest tokens still carry the old config. Regenerate your guest token or reload your app.

Server won't start

Make sure you have Node.js 18+ installed:

node --version  # Should be v18.0.0 or higher

How it works

Your AI Client                    MCP Server                  Databrain API
(Codex, Claude, Cursor, etc.) ←→  (this package)       ←→     (your data, dashboards, embeds)

The MCP server translates natural language requests into Databrain actions. It manages authentication (service tokens, API tokens, guest tokens), validates inputs, and provides guided workflows so you don't need to learn the Databrain API directly.

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.

Links

• Databrain — Sign up and create dashboards
• Databrain Docs — Full platform documentation
• MCP Protocol — Learn about Model Context Protocol

License

MIT