@databrainhq/mcp-server 0.2.9 → 0.2.11

package/README.md

@@ -15,12 +15,14 @@ Works with Claude, Cursor, Windsurf, and any MCP-compatible client.
 
 ### 1. Get your Service Token
 
-1. Log in to [Databrain](https://usedatabrain.com)
+1. Log in to your Databrain instance (cloud or self-hosted)
 2. Go to **Settings → Service Tokens**
 3. Create a new token and copy it
 
 ### 2. Add to your AI client
 
+> **Self-hosted?** Also set `DATABRAIN_API_URL` in the `env` block — see [Self-hosted Databrain](#self-hosted-databrain) below.
+
 <details>
 <summary><b>Cursor</b></summary>
 
@@ -105,6 +107,32 @@ npx @databrainhq/mcp-server
 ```
 </details>
 
+### Self-hosted Databrain
+
+Running Databrain on your own infrastructure? Point the MCP server at your instance by setting `DATABRAIN_API_URL` alongside your token:
+
+```json
+{
+  "mcpServers": {
+    "databrain": {
+      "command": "npx",
+      "args": ["@databrainhq/mcp-server"],
+      "env": {
+        "DATABRAIN_PAT": "<your-personal-access-token>",
+        "DATABRAIN_API_URL": "https://api.your-databrain.example.com"
+      }
+    }
+  }
+}
+```
+
+Checklist:
+- `DATABRAIN_API_URL` must be the **API origin** for your self-hosted instance (not the dashboard URL). Typically `https://api.<your-domain>`.
+- The token must be minted from that same self-hosted instance — tokens are not portable across instances.
+- Use `DATABRAIN_PAT` (Settings → Personal Access Tokens) for per-user role checks and audit. Use `DATABRAIN_SERVICE_TOKEN` if you want the MCP server to act with full org-level privileges (no per-user audit).
+- The MCP client process must be able to reach the URL (VPN, firewall, self-signed certs all apply here).
+- Scaffolded frontend code (React, Next.js, Vue, etc.) reads the same `DATABRAIN_API_URL` for server-side guest-token generation, so the variable flows through to your app.
+
 ### 3. Start talking
 
 Open your AI assistant and try any of these:
@@ -165,7 +193,7 @@ Each of your customers gets their own dashboard with row-level security.
 
 ### Tweak widgets on a customer dashboard
 
-Add, remove, or modify widgets (metrics) on a specific customer's embed without opening the Databrain UI. Clone from a template widget, write a fresh SQL spec, or generate one from a prompt.
+Add, remove, or modify widgets (metrics) on a specific customer's embed without opening the Databrain UI. Clone from a template widget, write a fresh SQL spec, or generate one from a prompt. End with a demo link to verify exactly what that customer will see — same URL the UI's "Share Demo Link" generates.
 
 > "Add the 'Calls per day' widget from the standard template to Acme's dashboard"
 
@@ -173,6 +201,8 @@ Add, remove, or modify widgets (metrics) on a specific customer's embed without
 
 > "Remove the billing widget from Acme's dashboard but keep it for other customers"
 
+> "Give me a demo link for Acme's dashboard so I can see what they'll see"
+
 ### Enable self-serve analytics
 
 Let end-users build their own metrics with drag-and-drop or AI-powered chat.
@@ -191,11 +221,17 @@ Let end-users build their own metrics with drag-and-drop or AI-powered chat.
 
 ## Environment Variables
 
+At least one of `DATABRAIN_PAT`, `DATABRAIN_SERVICE_TOKEN`, or `DATABRAIN_API_TOKEN` must be set. PAT is preferred — it binds the MCP session to a specific user so role checks and audit logs work correctly.
+
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `DATABRAIN_SERVICE_TOKEN` | **Yes** | — | Org-level token from Settings → Service Tokens. Powers all discovery and setup operations. |
-| `DATABRAIN_API_TOKEN` | No | — | Per-data-app token. Created automatically during setup via `create_api_token`, or set manually if you already have one. |
-| `DATABRAIN_API_URL` | No | `https://api.usedatabrain.com` | API base URL. Only change this for self-hosted Databrain. |
+| `DATABRAIN_PAT` | One of three† | — | Personal Access Token from Settings → Personal Access Tokens. Binds the MCP session to your Databrain user — actions are role-checked and audited under your account. **Preferred for sandboxed hosts** (Claude Desktop, ChatGPT Desktop) and headless/CI environments where local credential caching isn't reliable. |
+| `DATABRAIN_SERVICE_TOKEN` | One of three† | — | Org-level token from Settings → Service Tokens. Powers all discovery and setup operations. The `connect` tool can mint a PAT on top of this for per-user audit. |
+| `DATABRAIN_API_TOKEN` | One of three† | — | Per-data-app token. Created automatically during setup via `create_api_token`, or set manually if you already have one. |
+| `DATABRAIN_API_URL` | **Required for self-hosted** | `https://api.usedatabrain.com` | API base URL. Set to your instance's API origin (e.g. `https://api.your-databrain.example.com`). |
+| `DATABRAIN_DEMO_DOMAIN` | Optional | `https://demo.usedatabrain.com` | Base host for `get_demo_link` URLs. Override for self-hosted instances or custom preview domains (e.g. `https://demo.your-databrain.example.com`). |
+
+† At least one of these three credentials must be set. Token resolution priority: `DATABRAIN_PAT` > cached PAT (from `connect`) > `DATABRAIN_SERVICE_TOKEN` > `DATABRAIN_API_TOKEN`.
 
 ---
 
@@ -216,12 +252,12 @@ Prompts are guided workflows your AI assistant can follow. Ask for them by name
 
 ## Tools Reference
 
-26 tools organized by category. Your AI assistant picks the right tools automatically — you don't need to call them directly.
+29 tools organized by category. Your AI assistant picks the right tools automatically — you don't need to call them directly.
 
 > **Note:** Infrastructure creation (datasources, datamarts, workspaces) is done in the **Databrain UI**. However, the **semantic layer** is populated via MCP tools (`get_semantic_layer`, `update_semantic_layer`) — the AI auto-generates descriptions from column names.
 
 <details>
-<summary><b>Infrastructure — Exploration & Linking</b> (5)</summary>
+<summary><b>Infrastructure — Exploration</b> (4)</summary>
 
 | Tool | Description |
 |------|-------------|
@@ -229,7 +265,6 @@ Prompts are guided workflows your AI assistant can follow. Ask for them by name
 | `discover_datasource_schema` | Inspect a datasource to see available tables and columns |
 | `list_datamarts` | List datamarts |
 | `list_workspaces` | List all workspaces (shows datamart/datasource connections) |
-| `link_datamart_to_workspace` | Link a datamart to an existing workspace |
 </details>
 
 <details>
@@ -245,15 +280,16 @@ Prompts are guided workflows your AI assistant can follow. Ask for them by name
 </details>
 
 <details>
-<summary><b>Embeds</b> (5) — Create, configure, and customize embedded dashboards</summary>
+<summary><b>Embeds</b> (6) — Create, configure, and customize embedded dashboards</summary>
 
 | Tool | Description |
 |------|-------------|
 | `create_embed` | Create an embed (standard or multi-tenant with `clientId`) |
-| `list_embeds` | List embed configurations |
+| `list_embeds` | List embed configurations (includes `distinctClientIds` for multi-tenant client discovery) |
 | `get_embed_details` | Get full embed details by ID |
 | `update_embed` | Update embed config — access settings, options, filters, i18n (via `body` passthrough) |
 | `customize_embed_theme` | Presets, colors, fonts, cards, chart appearance, responsive layout |
+| `get_demo_link` | Get a shareable demo URL for a `clientId` — same link the UI's "Share Demo Link" generates. Use to preview ops-built widgets without a test app |
 </details>
 
 <details>