Skip to Content

MCP Server

Set up your AI app

Add the Databrain MCP server to ChatGPT, Cursor, VS Code, Claude Code, Codex or a stdio client.

Each AI app needs the server URL from Settings > MCP. That page also shows the steps and the ready command for each app below.

Where you use DatabrainServer URL
Databrain cloudhttps://mcp.usedatabrain.com/mcp
Self-hostedYour app address followed by /mcp, for example https://analytics.example.com/mcp

Hosted connector

You sign in to Databrain from the app and choose the workspaces it can use. See Connect Claude for the sign-in page.

Claude (claude.ai and Claude Desktop)

  1. In Claude, go to Settings > Connectors and select Add custom connector.
  2. Enter the name Databrain and paste the server URL.
  3. Select Connect and sign in to Databrain.

Custom connectors need a paid Claude plan.

ChatGPT

  1. In ChatGPT, add a custom connector. A workspace admin may need to allow it.
  2. Paste the server URL and choose OAuth as the sign-in.
  3. Connect and sign in to Databrain.

Cursor

Select Add to Cursor in Settings > MCP, or add this to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "databrain": { "url": "https://mcp.usedatabrain.com/mcp" }
  }
}

Cursor asks you to sign in to Databrain the first time a tool runs.

VS Code (GitHub Copilot agent mode)

Select Add to VS Code in Settings > MCP, or run:

code --add-mcp '{"name":"databrain","type":"http","url":"https://mcp.usedatabrain.com/mcp"}'

VS Code asks you to sign in to Databrain when the server starts.

Claude Code

claude mcp add --transport http databrain https://mcp.usedatabrain.com/mcp

In Claude Code, run /mcp, pick databrain and sign in.

Codex

codex mcp add databrain --url https://mcp.usedatabrain.com/mcp
codex mcp login databrain

The login opens the Databrain sign-in page in your browser. If the page shows a sign-in code, select Copy code, go back to your terminal, paste it and press Enter.

Local server with a service token

Use this for CI, scripts, Windsurf and other clients that start a local process (stdio). Calls act as the organization, not as you, and the audit log shows actor=system.

Before you start

  • Node.js 20 or later.
  • A service token. Go to Settings > Tokens, open Service Tokens and create one. You see the token once, so copy it then.

Add the server

Add this to your client’s MCP config (Claude Desktop, Cursor, Windsurf and most stdio clients use this shape):

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

For Codex:

codex mcp add databrain --env DATABRAIN_SERVICE_TOKEN=<your-service-token> -- npx @databrainhq/mcp-server

Settings > MCP > Show service token setup builds this config for Codex, Claude Code, Cursor, Claude Desktop, Windsurf and other clients. Its Test connection button checks that a token works against the API. The token you paste there is not saved.

Environment variables

VariableRequiredDefaultWhat it does
DATABRAIN_SERVICE_TOKENOne of the two tokensOrganization token from Settings > Tokens. Used for setup, data apps, the semantic layer and metric writes.
DATABRAIN_API_TOKENOne of the two tokensData app API token. Enough for embed work in one data app. The service token wins when both are set.
DATABRAIN_API_URLSelf-hosted onlyhttps://api.usedatabrain.comYour API address, not the app address.
DATABRAIN_DEMO_DOMAINNohttps://demo.usedatabrain.comHost for the links that get_demo_link returns.
DATABRAIN_OAUTH_ISSUER, DATABRAIN_OAUTH_CLIENT_ID, DATABRAIN_OAUTH_CLIENT_SECRETInstead of a tokenOAuth client credentials for a service identity. Optional: DATABRAIN_OAUTH_SCOPE, DATABRAIN_OAUTH_RESOURCE, DATABRAIN_OAUTH_AUTH_METHOD. DATABRAIN_API_URL must use HTTPS.

A token works only on the Databrain instance that made it. A cloud token does not work on a self-hosted instance.

The local server sends anonymous usage events to Databrain when it talks to Databrain cloud. With a self-hosted DATABRAIN_API_URL it sends none.

Chart tiles in chat (optional)

AI apps that show MCP Apps can draw charts and KPI tiles inside the chat. Start the server with the chart entry instead:

{
  "command": "npx",
  "args": ["--yes", "--package", "@databrainhq/mcp-server", "databrain-mcp-chart-apps"]
}

The hosted connector has the chart tiles already.

Self-hosted Databrain

  • Hosted connector: your admin turns on the MCP server container. The URL is your app address followed by /mcp. See Self-hosted MCP.
  • Local server: set DATABRAIN_API_URL to your API address and use a service token from your instance.

If Settings > MCP says Sign-in for AI apps is turned off on this Databrain install, the hosted connector is off. Use a service token, or ask your admin to turn it on.

Next, see what you can ask.