Skip to Content

Self-Hosted Deployment

Point embeds and AI apps at your instance

Make the embed plugin call your self-hosted API, and turn on the MCP server for AI apps.

Point the embed plugin at your API

The @databrainhq/plugin package calls Databrain cloud by default. On a self-hosted install, give it your API address with the base-url attribute:

<dbn-dashboard
  token="<guest-token>"
  dashboard-id="<dashboard-id>"
  base-url="https://api.analytics.example.com"
></dbn-dashboard>

dbn-metric takes the same attribute. Use your API address, not the app address. A trailing slash is removed.

You can also set it once for the page, before the component loads:

window.dbn = { ...window.dbn, baseUrl: "https://api.analytics.example.com" };

If more than one is set, the plugin uses the first of these:

  1. window.dbn.proxyAuthUrl (see Proxy authentication)
  2. window.dbn.baseUrl
  3. The base-url attribute
  4. The default built into the package

The address is one value for the whole page. If two embeds on one page ask for different addresses, the last one wins and the browser console shows a warning. Use one API address per page.

Check it: open your page, open the browser’s network tab, and confirm the requests go to your API address.

Turn on the MCP server

AI apps such as Claude, ChatGPT and Cursor connect to <your app address>/mcp and sign in against your own install. The MCP server is off by default.

Before you start

  • HOSTED_APP_URL uses https and has no trailing slash. With http://localhost, the MCP server does not start.
  • The app image is the same release as the MCP image.

Docker Compose

  1. Put databrain-mcp.yml from your release next to docker-compose.yml.

  2. Add this line to .env:

    COMPOSE_FILE=docker-compose.yml:databrain-mcp.yml
  3. Run docker compose up -d.

This adds the databrainmcp service on port 3144. It reads HOSTED_APP_URL and DBN_VERSION, which your install already has. The app routes /mcp to it.

Kubernetes or your own container definitions

Add one container next to the others, with the same tag, that the app container reaches as databrainmcp:3144:

SettingValue
Imagepublic.ecr.aws/databrain/dbn-mcp-multix:<same tag as your other images>
DATABRAIN_HOSTED_PUBLIC_URL<HOSTED_APP_URL>/mcp
DATABRAIN_HOSTED_ISSUER<HOSTED_APP_URL>
DATABRAIN_HOSTED_BIND0.0.0.0
DATABRAIN_HOSTED_PORT3144
Health checkGET /health on port 3144

If your ingress sends paths straight to services, route /mcp to the MCP container. Route /.well-known/oauth-* and the /oauth/* API paths to the backend, and the /oauth/authorize?request_id=, /oauth/code and /oauth/success pages to the app. Your load balancer must pass the original Host header.

Check it

  1. Go to Settings > MCP in your install. Server URL shows <your app address>/mcp.
  2. Connect an AI app. See Connect Claude to Databrain.

Turn it off

  • Remove the COMPOSE_FILE line and run docker compose up -d --remove-orphans. /mcp then answers 503 mcp_unavailable.
  • Or set OAUTH_PROVIDER_ENABLED=false on the backend. This turns off sign-in for all AI apps. Settings > MCP then says “Sign-in for AI apps is turned off on this Databrain install”.

The local MCP server with a service token works without any of this. Set DATABRAIN_API_URL to your API address. See Set up your AI app.