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
Codex
Cursor
Claude Desktop
Claude Code
Windsurf
Generic / stdio
Add via CLI
codex mcp add databrain --env DATABRAIN_SERVICE_TOKEN=YOUR_SERVICE_TOKEN -- npx @databrainhq/mcp-server
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
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>"
Verify
You should see databrain in the list of configured servers.Config File Location
~/.codeium/windsurf/mcp_config.jsonConfiguration
{
"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"
}
}
}
}
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.
{
"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 |
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. 
