Client Setup

This guide covers full configuration for each supported AI client, including file paths, restart steps, self-hosted setup, and optional API-token-only configuration.

Configuration by Client

Add via CLI

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

Replace YOUR_SERVICE_TOKEN with your Databrain service token.

Self-Hosted

For a self-hosted Databrain instance, include the API URL:

codex mcp add databrain \
  --env DATABRAIN_SERVICE_TOKEN=YOUR_SERVICE_TOKEN \
  --env DATABRAIN_API_URL=https://api.your-databrain.example.com \
  --env DATABRAIN_DEMO_DOMAIN=https://demo.your-databrain.example.com \
  -- npx @databrainhq/mcp-server

Verify

codex mcp list

Start a new Codex session after adding or updating the server.

Config File Location

Project-level: .cursor/mcp.json in your project root
Global: ~/.cursor/mcp.json

Project-level config takes precedence when both exist.

Configuration

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

Restart

After saving the config file, restart Cursor or reload the window (Cmd+Shift+P -> “Reload Window”) to pick up the new MCP server.

Config File Location

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuration

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

Restart

Fully quit Claude Desktop and reopen it. On macOS, use Cmd+Q to quit.

Add via CLI

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

Set Environment Variable

Add to your shell profile (.bashrc, .zshrc, etc.):

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

Then reload your shell:

source ~/.zshrc

Verify

claude mcp list

You should see databrain in the list of configured servers.

Config File Location

~/.codeium/windsurf/mcp_config.json

Configuration

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

Restart

Restart Windsurf after saving the config file.

Direct Execution

The server uses stdio transport and works with any MCP-compatible client.

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

Programmatic Usage

If your client accepts a command and arguments:

Command: npx
Args: ["@databrainhq/mcp-server"]
Env: { "DATABRAIN_SERVICE_TOKEN": "<your-service-token>" }

Self-Hosted Databrain

If you’re running a self-hosted Databrain instance, set DATABRAIN_API_URL to the API origin for that instance.

{
  "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, not the dashboard URL.
The token must be minted from that same self-hosted instance. Tokens are not portable across instances.
The MCP client process must be able to reach the URL through your VPN, firewall, or certificate setup.
Set DATABRAIN_DEMO_DOMAIN if get_demo_link should use a custom preview host.

API-Token-Only Mode

By default, use a service token. It lets the MCP server discover resources, manage data apps, create API tokens, and run semantic-layer workflows. If you only need operations inside one existing data app, you can configure an API token instead:

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

API-token-only mode is scoped to one data app. It supports embed, guest token, widget, demo link, and scheduled report metadata operations, but org-level discovery and setup tools require DATABRAIN_SERVICE_TOKEN.

You can also provide both tokens:

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

Environment Variables Reference

Variable	Required	Default	Description
`DATABRAIN_SERVICE_TOKEN`	One of two	-	Org-level token from Settings -> Service Tokens
`DATABRAIN_API_TOKEN`	One of two	-	Per-data-app token used for embed, widget, guest token, demo link, and report metadata operations
`DATABRAIN_API_URL`	Required for self-hosted	`https://api.usedatabrain.com`	API base URL
`DATABRAIN_DEMO_DOMAIN`	No	`https://demo.usedatabrain.com`	Hosted preview base URL for `get_demo_link`

At least one of DATABRAIN_SERVICE_TOKEN or DATABRAIN_API_TOKEN must be set. If both are set, service-token mode is used for org-level operations.

Verifying the Connection

After configuring your client, try asking your AI assistant:

“Who am I authenticated as in Databrain?”

This calls whoami and confirms whether the server is running in service-token or API-token mode. Then ask:

“List my Databrain data apps”

If you get a missing-token configuration error, double-check that the token is set in the env block of your MCP config and restart your client. See the Troubleshooting guide for common issues and solutions.

Embedding Setup

MCP Server

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

Configuration by Client

Add via CLI

Self-Hosted

Verify

Config File Location

Configuration

Restart

Config File Location

Configuration

Restart

Add via CLI

Set Environment Variable

Verify

Config File Location

Configuration

Restart

Direct Execution

Programmatic Usage

Self-Hosted Databrain

API-Token-Only Mode

Environment Variables Reference

Verifying the Connection

​Configuration by Client

​Add via CLI

​Self-Hosted

​Verify

​Config File Location

​Configuration

​Restart

​Config File Location

​Configuration

​Restart

​Add via CLI

​Set Environment Variable

​Verify

​Config File Location

​Configuration

​Restart

​Direct Execution

​Programmatic Usage

​Self-Hosted Databrain

​API-Token-Only Mode

​Environment Variables Reference

​Verifying the Connection

Configuration by Client

Add via CLI

Self-Hosted

Verify

Config File Location

Configuration

Restart

Config File Location

Configuration

Restart

Add via CLI

Set Environment Variable

Verify

Config File Location

Configuration

Restart

Direct Execution

Programmatic Usage

Self-Hosted Databrain

API-Token-Only Mode

Environment Variables Reference

Verifying the Connection