Quickstart - Databrain

You’ll need a Databrain account, Node.js 18+, and an MCP-compatible AI client. A service token is recommended because it unlocks the full setup flow.

Prerequisites

Node.js 18+ - check with node --version
A Databrain account - sign up here if you don’t have one
An AI client - Codex, Cursor, Claude Desktop, Claude Code, Windsurf, or another MCP-compatible client
A Databrain credential - preferably DATABRAIN_SERVICE_TOKEN

Get Your Service Token

Log in to Databrain
Go to Settings -> Service Tokens
Create a new token and copy it

Keep your service token secure. It provides org-level access to Databrain resources.

Add to Your AI Client

Add the MCP server configuration to your client. Pick your client 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-level) 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 in the shell that launches Claude Code:

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

For detailed per-client instructions, API-token-only mode, restart steps, and self-hosted configuration, see the Client Setup Guide.

Verify the Connection

Open your AI assistant and ask:

“Who am I authenticated as in Databrain?”

This calls whoami and confirms whether the MCP server is running with a service token or API token.Then ask:

“List my Databrain data apps”

If everything is configured correctly, you’ll see your available data apps.

If you see a configuration error saying that no token is set, double-check that the token is in the env block of your MCP config and restart your AI client. See Troubleshooting for more help.

Try It Out

Now try a real task:

“Set up a Databrain embed for my dashboard”

The assistant walks you through each step interactively: picking your data app, selecting a workspace and dashboard, creating or reusing an embed, generating a guest token, and generating frontend code.Other things to try:

“Add a widget to a customer’s dashboard”

“List tenants for my workspace so I can pick the right clientId”

“Dry-run creating this SQL query as a Databrain metric”

“Enable self-serve metric creation on this embed”

“Brand my embed to match our company colors”

That’s it. The assistant handles the Databrain API so you can focus on building.

Credential Modes

Mode	When to use it	What works
Service token	Recommended default	Full discovery, tenant lookup, setup, semantic layer, data app management, and production-safe datamart and workspace-metric operations
API token	Existing single-data-app embed work	Embed operations, guest tokens, widget operations, demo links, and scheduled report metadata for that data app

If both tokens are configured, the MCP server prefers DATABRAIN_SERVICE_TOKEN for org-level operations and can activate per-data-app API tokens during setup.

Next Steps

Workflows

Step-by-step guides for common tasks

Client Setup

Detailed configuration per client

Tools Reference

All 36 tools

​Prerequisites

​Credential Modes

​Next Steps

Workflows

Client Setup

Tools Reference

Prerequisites

Credential Modes

Next Steps