@databrainhq/mcp-server 0.2.11 → 0.2.13

package/README.md

@@ -1,13 +1,13 @@
 # @databrainhq/mcp-server
 
-Add embedded analytics to your app using natural language. Connect this MCP server to any AI assistant and describe what you want — it handles the Databrain API for you.
+Add embedded analytics to your app using natural language. Connect this MCP server to any AI assistant and describe what you want — it handles the setup steps for you.
 
 ```
 "What was total revenue last month?"
 "Embed my sales dashboard in my React app"
 ```
 
-Works with Claude, Cursor, Windsurf, and any MCP-compatible client.
+Works with Codex, Claude, Cursor, Windsurf, and any MCP-compatible client.
 
 ---
 
@@ -23,6 +23,24 @@ Works with Claude, Cursor, Windsurf, and any MCP-compatible client.
 
 > **Self-hosted?** Also set `DATABRAIN_API_URL` in the `env` block — see [Self-hosted Databrain](#self-hosted-databrain) below.
 
+<details>
+<summary><b>Codex</b></summary>
+
+Add the MCP server with your service token:
+
+```bash
+codex mcp add databrain --env DATABRAIN_SERVICE_TOKEN=YOUR_SERVICE_TOKEN -- npx @databrainhq/mcp-server
+```
+
+Verify the server is configured:
+
+```bash
+codex mcp list
+```
+
+Start a new Codex session after adding the server.
+</details>
+
 <details>
 <summary><b>Cursor</b></summary>
 
@@ -118,8 +136,9 @@ Running Databrain on your own infrastructure? Point the MCP server at your insta
       "command": "npx",
       "args": ["@databrainhq/mcp-server"],
       "env": {
-        "DATABRAIN_PAT": "<your-personal-access-token>",
-        "DATABRAIN_API_URL": "https://api.your-databrain.example.com"
+        "DATABRAIN_SERVICE_TOKEN": "<your-service-token>",
+        "DATABRAIN_API_URL": "https://api.your-databrain.example.com",
+        "DATABRAIN_DEMO_DOMAIN": "https://demo.your-databrain.example.com"
       }
     }
   }
@@ -129,7 +148,7 @@ Running Databrain on your own infrastructure? Point the MCP server at your insta
 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).
+- Use `DATABRAIN_SERVICE_TOKEN` (Settings → Service Tokens) for org-level access.
 - 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.
 
@@ -139,7 +158,7 @@ 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?"**
 
@@ -195,13 +214,21 @@ Each of your customers gets their own dashboard with row-level security.
 
 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"
+> "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"
+
+> "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
 
-> "Give me a demo link for Acme's dashboard so I can see what they'll see"
+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
 
@@ -221,17 +248,16 @@ 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.
+At least one of `DATABRAIN_SERVICE_TOKEN` or `DATABRAIN_API_TOKEN` must be set. Use a service token for full setup and management flows; use an API token only when you are operating inside one data app.
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `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_SERVICE_TOKEN` | One of two† | — | Org-level token from Settings → Service Tokens. Powers discovery, setup, data app management, semantic layer, and production-safe datamart operations. |
+| `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 three credentials must be set. Token resolution priority: `DATABRAIN_PAT` > cached PAT (from `connect`) > `DATABRAIN_SERVICE_TOKEN` > `DATABRAIN_API_TOKEN`.
+† At least one of these two credentials must be set. Token resolution priority: `DATABRAIN_SERVICE_TOKEN` > `DATABRAIN_API_TOKEN`.
 
 ---
 
@@ -247,17 +273,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
 
-29 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</b> (4)</summary>
+<summary><b>Infrastructure — Exploration and setup</b> (6)</summary>
 
 | Tool | Description |
 |------|-------------|
@@ -265,6 +292,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) |
+| `sync_datasource` | Trigger datasource schema sync |
+| `create_datamart` | Dry-run or create a datamart from selected tables and relationships |
 </details>
 
 <details>
@@ -287,9 +316,9 @@ Prompts are guided workflows your AI assistant can follow. Ask for them by name
 | `create_embed` | Create an embed (standard or multi-tenant with `clientId`) |
 | `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) |
+| `update_embed` | Update embed config — access settings, options, filters, i18n, and advanced embed options |
 | `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 |
+| `get_demo_link` | Get a shareable demo URL for a `clientId` — same link the UI's "Share Demo Link" generates |
 </details>
 
 <details>
@@ -302,28 +331,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 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 |
-| `add_widget` | Add a widget — clone from a template (`templateMetricId`), supply a full spec, or pass a raw body from `generate_widget` |
+| `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 metric configuration, or use a generated draft |
 | `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.
+Provide `clientId` and `dashboardName`; include `workspaceName` only if dashboard names are ambiguous. The tools resolve the required resources automatically.
+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 |
 </details>
 
 ---
@@ -384,13 +426,11 @@ node --version  # Should be v18.0.0 or higher
 ## How it works
 
 ```
-Your AI Client ←→ MCP Server ←→ Databrain API
-    (Claude,         (this           (your data,
-     Cursor,        package)         dashboards,
-     etc.)                           embeds)
+Your AI Client                    MCP Server                  Databrain API
+(Codex, Claude, Cursor, etc.) ←→  (this package)       ←→     (your data, dashboards, embeds)
 ```
 
-The MCP server translates natural language requests into Databrain API calls. It manages authentication (service tokens, API tokens, guest tokens), validates inputs, and provides guided workflows so you don't need to learn the Databrain API directly.
+The MCP server translates natural language requests into Databrain actions. It manages authentication (service tokens, API tokens, guest tokens), validates inputs, and provides guided workflows so you don't need to learn the Databrain API directly.
 
 All tokens are managed automatically. You provide your service token once in the config — everything else is created and handled by the server during setup.