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

# Client Setup

> Detailed configuration instructions for each AI client

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

<Tabs>
  <Tab title="Codex">
    ### Add via CLI

    ```bash theme={"dark"}
    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:

    ```bash theme={"dark"}
    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

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

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

  <Tab title="Cursor">
    ### 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

    ```json theme={"dark"}
    {
      "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.
  </Tab>

  <Tab title="Claude Desktop">
    ### Config File Location

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

    ### Configuration

    ```json theme={"dark"}
    {
      "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.
  </Tab>

  <Tab title="Claude Code">
    ### Add via CLI

    ```bash theme={"dark"}
    claude mcp add databrain -- npx @databrainhq/mcp-server
    ```

    ### Set Environment Variable

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

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

    Then reload your shell:

    ```bash theme={"dark"}
    source ~/.zshrc
    ```

    ### Verify

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

    You should see `databrain` in the list of configured servers.
  </Tab>

  <Tab title="Windsurf">
    ### Config File Location

    `~/.codeium/windsurf/mcp_config.json`

    ### Configuration

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

    ### Restart

    Restart Windsurf after saving the config file.
  </Tab>

  <Tab title="Generic / stdio">
    ### Direct Execution

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

    ```bash theme={"dark"}
    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>" }`
  </Tab>
</Tabs>

***

## Self-Hosted Databrain

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

```json theme={"dark"}
{
  "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:

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

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

You can also provide both tokens:

```json theme={"dark"}
{
  "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](/developer-docs/mcp-server/troubleshooting) for common issues and solutions.