@databrainhq/mcp-server 0.2.10 → 0.2.12

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,13 +107,39 @@ 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_SERVICE_TOKEN": "<your-service-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_SERVICE_TOKEN` (Settings → Service Tokens) for org-level access. Per-user identity binding will arrive with the OAuth-based login flow now in development.
+- 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:
 
 > **"Set up a Databrain embed for my dashboard"**
 
-> **"Brand my embed to match our company colors"**
+> **"Brand my embed to match our colors"**
 
 > **"What was total revenue last month?"**
 
@@ -165,13 +193,23 @@ 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 a client's dashboard"
+
+> "Generate a widget showing disqualification reasons and add it to a client's embed"
 
-> "Add the 'Calls per day' widget from the standard template to Acme's dashboard"
+> "Remove the billing widget from one client's dashboard but keep it for other clients"
 
-> "Generate a widget showing disqualification reasons for Acme and add it to their embed"
+> "Give me a demo link for a client's dashboard so I can see what they'll see"
 
-> "Remove the billing widget from Acme's dashboard but keep it for other customers"
+### Migrate validated SQL into metrics
+
+Turn warehouse-validated SQL into Databrain metrics with a production-safe flow: validate the target dashboard/datasource, produce a dry-run plan, then apply only after explicit confirmation.
+
+> "Validate this SQL as a new metric on my operations dashboard"
+
+> "Dry-run creating this converted query as a metric, then show me the exact apply plan"
 
 ### Enable self-serve analytics
 
@@ -191,11 +229,16 @@ Let end-users build their own metrics with drag-and-drop or AI-powered chat.
 
 ## Environment Variables
 
+At least one of `DATABRAIN_SERVICE_TOKEN` or `DATABRAIN_API_TOKEN` must be set. Per-user identity binding (OAuth-based login) is in active development — until it ships, sessions authenticate at the org / data-app level.
+
 | 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_SERVICE_TOKEN` | One of two† | — | Org-level token from Settings → Service Tokens. Powers all discovery and setup operations. Audit logs record actions as `actor=system` until per-user OAuth login ships. |
+| `DATABRAIN_API_TOKEN` | One of two† | — | Per-data-app token. Created automatically during setup via `create_api_token`, or set manually if you already have one. Sufficient for embedding operations on a single data app. |
+| `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 two credentials must be set. Token resolution priority: `DATABRAIN_SERVICE_TOKEN` > `DATABRAIN_API_TOKEN`.
 
 ---
 
@@ -211,17 +254,18 @@ Prompts are guided workflows your AI assistant can follow. Ask for them by name
 | `brand-my-embed` | Customize colors, fonts, charts, card styling, responsive layout |
 | `query-data` | Query your data with natural language, manage the semantic layer |
 | `populate-semantic-layer` | Auto-generate table/column descriptions to enable natural language querying |
+| `sql-to-metric-migration` | Production-safe SQL-to-metric workflow: validate, dry-run, then apply with explicit confirmation |
 
 ---
 
 ## Tools Reference
 
-26 tools organized by category. Your AI assistant picks the right tools automatically — you don't need to call them directly.
+34 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.
+> **Note:** Datasource and workspace creation happen outside MCP. Datamarts can be planned with `create_datamart` in `dry_run` mode and created only with `confirm: "APPLY_TO_PRODUCTION"`. The semantic layer is managed via MCP tools (`get_semantic_layer`, `update_semantic_layer`, `start_semantic_layer_generation`, `get_semantic_layer_generation_status`).
 
 <details>
-<summary><b>Infrastructure — Exploration & Linking</b> (5)</summary>
+<summary><b>Infrastructure — Exploration and setup</b> (6)</summary>
 
 | Tool | Description |
 |------|-------------|
@@ -229,7 +273,8 @@ 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 |
+| `sync_datasource` | Trigger datasource schema sync |
+| `create_datamart` | Dry-run or create a datamart from selected tables and relationships |
 </details>
 
 <details>
@@ -245,15 +290,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>
@@ -266,28 +312,41 @@ Prompts are guided workflows your AI assistant can follow. Ask for them by name
 </details>
 
 <details>
-<summary><b>Query & Semantic Layer</b> (3) — Ask questions and manage data documentation</summary>
+<summary><b>Query & Semantic Layer</b> (5) — Ask questions and manage data documentation</summary>
 
 | Tool | Description |
 |------|-------------|
 | `ask_question` | Ask a natural language question — gets converted to SQL, returns data + chart suggestion |
 | `get_semantic_layer` | Inspect semantic layer metadata (table/column descriptions, synonyms, completion score) |
 | `update_semantic_layer` | Improve semantic layer quality (add descriptions, synonyms, example questions) |
+| `start_semantic_layer_generation` | Start backend semantic-layer generation for a datamart |
+| `get_semantic_layer_generation_status` | Check semantic-layer generation progress |
 </details>
 
 <details>
-<summary><b>Dashboards & Widgets</b> (6) — Discover dashboards and CRUD widgets on customer embeds</summary>
+<summary><b>Dashboards & Widgets</b> (8) — Discover dashboards and CRUD widgets on customer embeds</summary>
 
 | Tool | Description |
 |------|-------------|
 | `list_dashboards` | List dashboards (by data app, workspace, or globally) |
 | `list_widgets` | List widgets on an embed for a specific client |
+| `validate_metric_spec` | Validate a SQL-backed metric target without saving |
+| `create_or_update_metric_from_query` | Dry-run or apply a SQL-backed metric create/update |
 | `add_widget` | Add a widget — clone from a template (`templateMetricId`), supply a full spec, or pass a raw body from `generate_widget` |
 | `update_widget` | Patch a widget's fields (name, query, chartOptions, isPublished, etc.) |
 | `remove_widget` | Per-client soft delete — hides the widget for one client only |
 | `generate_widget` | AI-generate a widget draft from a natural-language prompt. Returns a draft; pass to `add_widget` to persist |
 
 Widget mutation tools mint a guest token internally for `(clientId, dataAppName)`. Provide `embedId` + `clientId` — the tools resolve the rest.
+Production writes through `create_or_update_metric_from_query` default to `dry_run`; `apply` requires `confirm: "APPLY_TO_PRODUCTION"`.
+</details>
+
+<details>
+<summary><b>Scheduled Reports</b> (1)</summary>
+
+| Tool | Description |
+|------|-------------|
+| `list_scheduled_reports` | List configured scheduled reports for a dashboard/client scope. Delivery history is not part of this MCP/API surface yet |
 </details>
 
 ---