This is an automated email from the ASF dual-hosted git repository.
rusackas pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/superset.git
The following commit(s) were added to refs/heads/master by this push:
new 68f19947a80 docs(mcp): document semantic-layer MCP tools (#44130)
68f19947a80 is described below
commit 68f19947a8012ac587bb407c469abacbebae61ca
Author: Evan Rusackas <[email protected]>
AuthorDate: Sat Oct 3 21:57:29 2026 -0700
docs(mcp): document semantic-layer MCP tools (#44130)
Co-authored-by: Claude Sonnet 5 <[email protected]>
---
docs/admin_docs/configuration/mcp-server.mdx | 1 +
.../docs/using-superset/using-ai-with-superset.mdx | 35 ++++++++++++++++++++++
2 files changed, 36 insertions(+)
diff --git a/docs/admin_docs/configuration/mcp-server.mdx
b/docs/admin_docs/configuration/mcp-server.mdx
index b0358d3d375..6734952a23a 100644
--- a/docs/admin_docs/configuration/mcp-server.mdx
+++ b/docs/admin_docs/configuration/mcp-server.mdx
@@ -989,6 +989,7 @@ Each tool declares one or more required FAB permissions.
The table below maps to
| `list_dashboards`, `get_dashboard_info`, `generate_dashboard`,
`add_chart_to_existing_dashboard` | `can_read` on `Dashboard` (read),
`can_write` on `Dashboard` (mutate) |
| `get_dashboard_data`
| `can_read` on `Dashboard` **and** `can_read` on
`Chart` (it reads chart data across the dashboard) |
| `list_datasets`, `get_dataset_info`, `create_virtual_dataset`
| `can_read` on `Dataset` (read), `can_write` on
`Dataset` (mutate) |
+| `list_metrics`, `get_table`, `get_compatible_dimensions`,
`get_compatible_metrics` | `can_read` on `Dataset`, plus
a data-model metadata permission (`can_get_drill_info`,
`can_get_or_create_dataset`, or `can_write` on `Dataset`); external semantic
views also enforce their own datasource access check |
| `list_databases`, `get_database_info`
| `can_read` on `Database`
|
| `get_catalog`
| `can_read` on the requested asset class
(`Database`, `Dataset`, `Chart`, or `Dashboard`); databases and datasets also
require data-model metadata access, otherwise the page is marked `restricted` |
| `execute_sql`
| `can_execute_sql_query` on `SQLLab`
|
diff --git a/docs/docs/using-superset/using-ai-with-superset.mdx
b/docs/docs/using-superset/using-ai-with-superset.mdx
index c444166096c..7c3ed34d0cc 100644
--- a/docs/docs/using-superset/using-ai-with-superset.mdx
+++ b/docs/docs/using-superset/using-ai-with-superset.mdx
@@ -126,6 +126,32 @@ Build ad-hoc SQL datasets that can be used as the basis
for charts:
> "Create a dataset from: SELECT region, SUM(revenue) as total_revenue FROM
> orders GROUP BY region"
> "Make a virtual dataset called 'monthly_signups' from the users table
> filtered to last 12 months"
+### Query the Semantic Layer
+
+Discover and query metrics across both built-in datasets and external semantic
+views (when your deployment has semantic views registered), without writing
SQL:
+
+- **Discover metrics** -- search metrics by name or description across every
dataset and semantic view you can access, optionally including each metric's
compatible dimensions
+- **Query by metric and dimension** -- get tabular results by naming metrics
and dimensions instead of writing SQL, with optional filters and time ranges
+- **Progressively refine a query** -- given metrics and/or dimensions already
picked, see which dimensions and metrics are compatible with that selection
+
+**Example prompts:**
+
+> "What metrics are available related to revenue?"
+> "Show me revenue by region for the last 30 days"
+> "I've picked the revenue metric -- what dimensions can I break it down by?"
+
+:::tip Recommended workflow
+1. **`list_metrics`** -- search for a metric; note its `dataset_id` (built-in)
or `view_id` (external semantic view), plus its `semantic_selection_version`
when non-null
+2. **`get_table`** -- pass that `dataset_id`/`view_id` (and, for a versioned
external view, its `semantic_selection_version`) along with metric and
dimension names to get results
+3. **`get_compatible_dimensions`** / **`get_compatible_metrics`** -- as the
user adds selections, check what can validly be combined.
`get_compatible_dimensions` returns the full compatible set (including
dimensions already selected), so filter out your current picks client-side;
`get_compatible_metrics` already excludes selected metrics for built-in
datasets but not for external semantic views
+
+Built-in datasets accept any combination of saved metrics and groupby-enabled
+columns since a SQL `GROUP BY` has no metric-level constraints. External
+semantic views can impose additional compatibility rules, which these tools
+surface instead of failing the query outright.
+:::
+
### Run SQL Queries
Execute SQL directly through your AI assistant:
@@ -292,6 +318,15 @@ that those charts may need repair; deletion does not
rewrite charts. References
embedded in SQL expressions are not inferred. If a chart has malformed
query-context
JSON, impact reporting still checks its saved form data and other accessible
charts.
+### Semantic Layer
+
+| Tool | Description
|
+| ---------------------------- |
-----------------------------------------------------------------------------------------------------------------------------------
|
+| `list_metrics` | Discover metrics by name/description across
built-in datasets and external semantic views; pass
`include_compatible_dimensions` to embed each metric's compatible dimensions
(off by default) |
+| `get_table` | Query a dataset or semantic view by metric
and dimension names, with optional filters, time range, and sorting
|
+| `get_compatible_dimensions` | Given metrics/dimensions already selected,
return the full set of dimensions compatible with that selection (may include
ones already selected) |
+| `get_compatible_metrics` | Given metrics/dimensions already selected,
return the compatible metrics; already-selected metrics are excluded for
built-in datasets, while external semantic views return whatever their
connector reports and may include ones already selected |
+
### Charts
| Tool | Description
|
