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

# Quickstart

> Get the Databrain MCP server running in 2 minutes

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

## Prerequisites

* **Node.js 18+** - check with `node --version`
* **A Databrain account** - [sign up here](https://app.usedatabrain.com/users/sign-up) 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`

***

<Steps>
  <Step title="Get Your Service Token">
    1. Log in to [Databrain](https://app.usedatabrain.com)
    2. Go to **Settings -> Service Tokens**
    3. Create a new token and copy it

    <Warning>
      Keep your service token secure. It provides org-level access to Databrain resources.
    </Warning>
  </Step>

  <Step title="Add to Your AI Client">
    Add the MCP server configuration to your client. Pick your client below:

    <Tabs>
      <Tab title="Codex">
        Add the MCP server with your service token:

        ```bash theme={"dark"}
        codex mcp add databrain --env DATABRAIN_SERVICE_TOKEN=YOUR_SERVICE_TOKEN -- npx @databrainhq/mcp-server
        ```

        Verify the server is configured:

        ```bash theme={"dark"}
        codex mcp list
        ```

        Start a new Codex session after adding the server.
      </Tab>

      <Tab title="Cursor">
        Add to `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global):

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

      <Tab title="Claude Desktop">
        Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

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

      <Tab title="Claude Code">
        ```bash theme={"dark"}
        claude mcp add databrain -- npx @databrainhq/mcp-server
        ```

        Set your token in the shell that launches Claude Code:

        ```bash theme={"dark"}
        export DATABRAIN_SERVICE_TOKEN="<your-service-token>"
        ```
      </Tab>

      <Tab title="Windsurf">
        Add to `~/.codeium/windsurf/mcp_config.json`:

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

      <Tab title="Other">
        The server uses stdio transport. Set environment variables and run:

        ```bash theme={"dark"}
        export DATABRAIN_SERVICE_TOKEN="<your-service-token>"
        npx @databrainhq/mcp-server
        ```
      </Tab>
    </Tabs>

    For detailed per-client instructions, API-token-only mode, restart steps, and self-hosted configuration, see the [Client Setup Guide](/developer-docs/mcp-server/client-setup).
  </Step>

  <Step title="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.

    <Warning>
      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](/developer-docs/mcp-server/troubleshooting) for more help.
    </Warning>
  </Step>

  <Step title="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"**
  </Step>
</Steps>

<Check>
  That's it. The assistant handles the Databrain API so you can focus on building.
</Check>

***

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

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

***

## Next Steps

<CardGroup cols={3}>
  <Card title="Workflows" icon="route" href="/developer-docs/mcp-server/workflows">
    Step-by-step guides for common tasks
  </Card>

  <Card title="Client Setup" icon="gear" href="/developer-docs/mcp-server/client-setup">
    Detailed configuration per client
  </Card>

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