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 Databrain | Server URL |
|---|---|
| Databrain cloud | https://mcp.usedatabrain.com/mcp |
| Self-hosted | Your 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)
- In Claude, go to Settings > Connectors and select Add custom connector.
- Enter the name
Databrainand paste the server URL. - Select Connect and sign in to Databrain.
Custom connectors need a paid Claude plan.
ChatGPT
- In ChatGPT, add a custom connector. A workspace admin may need to allow it.
- Paste the server URL and choose OAuth as the sign-in.
- 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/mcpIn Claude Code, run /mcp, pick databrain and sign in.
Codex
codex mcp add databrain --url https://mcp.usedatabrain.com/mcp
codex mcp login databrainThe 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-serverSettings > 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
| Variable | Required | Default | What it does |
|---|---|---|---|
DATABRAIN_SERVICE_TOKEN | One of the two tokens | Organization token from Settings > Tokens. Used for setup, data apps, the semantic layer and metric writes. | |
DATABRAIN_API_TOKEN | One of the two tokens | Data app API token. Enough for embed work in one data app. The service token wins when both are set. | |
DATABRAIN_API_URL | Self-hosted only | https://api.usedatabrain.com | Your API address, not the app address. |
DATABRAIN_DEMO_DOMAIN | No | https://demo.usedatabrain.com | Host for the links that get_demo_link returns. |
DATABRAIN_OAUTH_ISSUER, DATABRAIN_OAUTH_CLIENT_ID, DATABRAIN_OAUTH_CLIENT_SECRET | Instead of a token | OAuth 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_URLto 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.