Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Show saved parameter settings in MCP dashboard responses (#85801)

Chris Truter791712156232
diff --git a/resources/mcp/v2/skills/dashboard-filters/SKILL.md b/resources/mcp/v2/skills/dashboard-filters/SKILL.md
index 53ba2725d8d..53ecf3a8473 100644
--- a/resources/mcp/v2/skills/dashboard-filters/SKILL.md
+++ b/resources/mcp/v2/skills/dashboard-filters/SKILL.md
@@ -15,7 +15,7 @@ dashboard_write {"method": "update", "id": 40,
"target_field": 18, "autowire": true}]}
```
-`parameter_id` is a short slug you choose and reuse in later ops; the server derives the URL slug from `name`. `get_content` on the dashboard lists each parameter's id, type, and wired dashcard ids.
+`parameter_id` is a short slug you choose and reuse in later ops; the server derives the URL slug from `name`. `get_content` on the dashboard lists each parameter's id, name, type, `default`, `required`, value source (`values_source_type` and `values_source_config`), and wired dashcard ids.
## Parameter types
@@ -68,8 +68,8 @@ Two hard constraints: linked filters read **table-metadata foreign keys only**
- Don't link a child filter that has a static-list/card source, or across a question/model join — the cascade silently doesn't apply.
- Don't pass null to clear a default or link — it reads as omitted; use `clear`.
- Don't hand-build a raw `target` when `target_field` or `target_tag` fits.
-- Don't report a default or link as set from the write response — read it back.
+- Don't report a link as set from the write response — read it back.
## To confirm
-`get_content {"type": "dashboard", "id": 40, "include": ["parameters"]}` — the write response is a skeleton without `default`, `filteringParameters`, or value-source config; read them back before reporting a default or link as set. Dropdown contents: `get_parameter_values`.
+`get_content {"items": [{"type": "dashboard", "id": 40}], "include": ["parameters"]}` — the write response shows each parameter's `default`, `required`, and value source, but not `filteringParameters`, `values_query_type`, or `isMultiSelect`; read those back before reporting a link or widget mode as set. Dropdown contents: `get_parameter_values`.
diff --git a/resources/mcp/v2/skills/dashboard-layout/SKILL.md b/resources/mcp/v2/skills/dashboard-layout/SKILL.md
index c5afeff060f..2e5b0233248 100644
--- a/resources/mcp/v2/skills/dashboard-layout/SKILL.md
+++ b/resources/mcp/v2/skills/dashboard-layout/SKILL.md
@@ -64,4 +64,4 @@ dashboard_write {"method": "create", "name": "Revenue overview",
## To confirm
-`get_content {"type": "dashboard", "id": 40, "include": ["layout"]}` returns every dashcard's tab, position, and size — check bands fill to 24 and every card has a tab. `validate_only: true` previews the same without saving.
+`get_content {"items": [{"type": "dashboard", "id": 40}], "include": ["layout"]}` returns every dashcard's tab, position, and size — check bands fill to 24 and every card has a tab. `validate_only: true` previews the same without saving.
diff --git a/resources/mcp/v2/skills/documents/SKILL.md b/resources/mcp/v2/skills/documents/SKILL.md
index 54a584b376c..b6ed29b7630 100644
--- a/resources/mcp/v2/skills/documents/SKILL.md
+++ b/resources/mcp/v2/skills/documents/SKILL.md
@@ -72,7 +72,7 @@ Edit one bullet - match its text only, never the `- ` marker, so the edit stays
## Comments
-`get_content {"type": "document", "id": 12, "include": ["comments"]}` returns threads grouped by anchored block, each with `anchor: {start, end, text}` — the exact character slice of the returned `content_markdown` — and `thread` messages (`id`, `creator`, `text`, `is_resolved`, `created_at`). A thread whose block was rewritten or deleted appears under `orphaned_comments`: the discussion still exists but points at no text, and only the UI can re-anchor it. MCP can read comments but not reply, resolve, or re-anchor — tell the user when a thread needs that.
+`get_content {"items": [{"type": "document", "id": 12}], "include": ["comments"]}` returns threads grouped by anchored block, each with `anchor: {start, end, text}` — the exact character slice of the returned `content_markdown` — and `thread` messages (`id`, `creator`, `text`, `is_resolved`, `created_at`). A thread whose block was rewritten or deleted appears under `orphaned_comments`: the discussion still exists but points at no text, and only the UI can re-anchor it. MCP can read comments but not reply, resolve, or re-anchor — tell the user when a thread needs that.
## Don't
@@ -84,4 +84,4 @@ Edit one bullet - match its text only, never the `- ` marker, so the edit stays
## To confirm
-`get_content {"type": "document", "id": 12}` returns the stored `content_markdown` (clone ids included); add `"include": ["layout"]` for the block outline, `["comments"]` for anchors. Rendering in the editor has no API check.
+`get_content {"items": [{"type": "document", "id": 12}]}` returns the stored `content_markdown` (clone ids included); add `"include": ["layout"]` for the block outline, `["comments"]` for anchors. Rendering in the editor has no API check.
diff --git a/src/metabase/mcp/v2/projections.clj b/src/metabase/mcp/v2/projections.clj
index fa34a3c2b66..c1194e5db78 100644
--- a/src/metabase/mcp/v2/projections.clj
+++ b/src/metabase/mcp/v2/projections.clj
@@ -249,24 +249,41 @@
(mapv #(m/remove-vals nil? (select-keys % [:id :name])) (:series dc)))
:inline_parameters (not-empty (:inline_parameters dc))}))
+(defn parameter-dashcard-ids
+ "A map from each wired parameter's id, as a string, to the sorted ids of `dash`'s dashcards wired to it.
+ A dry run's unsaved dashcards appear under their negative ids."
+ [dash]
+ (update-vals (reduce (fn [acc {dashcard-id :id :keys [parameter_mappings]}]
+ (reduce #(update %1 (u/qualified-name (:parameter_id %2)) (fnil conj #{}) dashcard-id)
+ acc
+ parameter_mappings))
+ {}
+ (:dashcards dash))
+ (comp vec sort)))
+
(defn- dashboard-parameters-summary
- "One row per dashboard parameter: id, name, type, and the ids of the dashcards it is wired
- to through their `:parameter_mappings`, including the negative ids of a dry run's unsaved dashcards."
+ "One row per dashboard parameter, with a subset of its stored properties and the ids of the dashcards wired to it."
[dash]
- (let [param-id->dashcard-ids (reduce (fn [acc {dashcard-id :id :keys [parameter_mappings]}]
- (reduce #(update %1 (u/qualified-name (:parameter_id %2)) (fnil conj #{}) dashcard-id)
- acc
- parameter_mappings))
- {}
- (:dashcards dash))]
+ (let [param-id->dashcard-ids (parameter-dashcard-ids dash)]
(mapv (fn [{param-id :id :as param}]
(m/remove-vals
nil?
- {:id param-id
- :name (:name param)
- :type (:type param)
- :dashcard_ids (not-empty
- (vec (sort (remove nil? (get param-id->dashcard-ids (u/qualified-name param-id))))))}))
+ ;; TODO (Chris 2026-10-30) -- decide with evals which parameter properties concise reads show.
+ ;; A static list's `values_source_config` holds every value, so a long list fills the agent's
+ ;; context in every concise read and every `dashboard_write` response.
+ ;; The row leaves out `values_query_type` and `isMultiSelect`, though a `"none"` query type means
+ ;; the widget is a text box that never offers the static list shown here.
+ {:id param-id
+ :name (:name param)
+ :type (:type param)
+ :default (:default param)
+ :required (:required param)
+ :values_source_type (:values_source_type param)
+ ;; A card source shows the card id and its value and label fields even to users who can't read the card.
+ ;; The REST endpoint `GET /api/dashboard/:id` returns stored parameters the same way, so
+ ;; redacting them only here would not keep them from those users.
+ :values_source_config (:values_source_config param)
+ :dashcard_ids (get param-id->dashcard-ids (u/qualified-name param-id))}))
(:parameters dash))))
(defn dashboard-row
@@ -292,7 +309,17 @@
(def ^:private dashboard-sample
(-> (zipmap dashboard-detailed-keys (repeat "x"))
(assoc :tabs [{:id 1 :name "x"}]
- :parameters [{:id "x" :name "x" :type "x" :dashcard_ids [1]}]
+ :parameters [{:id "x"
+ :name "x"
+ :type "x"
+ :default "x"
+ :required true
+ :values_source_type "x"
+ :values_source_config {:values ["x"]
+ :card_id 1
+ :value_field ["x"]
+ :label_field ["x"]}
+ :dashcard_ids [1]}]
:dashcards [{:id 1 :kind "x" :card {:id 1 :name "x"} :text "x" :dashboard_tab_id 1
:row 0 :col 0 :size_x 1 :size_y 1 :series [{:id 1 :name "x"}]
:inline_parameters ["x"]}])))
diff --git a/src/metabase/mcp/v2/tools/content.clj b/src/metabase/mcp/v2/tools/content.clj
index 27d017f1e80..fb534991920 100644
--- a/src/metabase/mcp/v2/tools/content.clj
+++ b/src/metabase/mcp/v2/tools/content.clj
@@ -19,6 +19,7 @@
subscription reads cover live Pulse rows and rows migrated to the notification API."
(:require
[clojure.string :as str]
+ [medley.core :as m]
[metabase.comments.core :as comments]
[metabase.documents.core :as documents]
[metabase.documents.prose-mirror :as prose-mirror]
@@ -394,6 +395,15 @@
u/remove-nils))
dashcards)}))
+(defn- dashboard-parameters
+ "The `parameters` include: each stored parameter with every property, and the ids of the dashcards wired to it.
+ The concise row shows only some of those properties."
+ [row]
+ (let [dash (::dashboard row)
+ param-id->dashcard-ids (projections/parameter-dashcard-ids dash)]
+ {:parameters (mapv #(m/assoc-some % :dashcard_ids (param-id->dashcard-ids (u/qualified-name (:id %))))
+ (:parameters dash))}))
+
;;; ----------------------------------------------------- alert ----------------------------------------------------
(defn- fetch-notification
@@ -508,7 +518,7 @@
"segment" {:fetch #(fetch-measure-or-segment :model/Segment %)
:includes {"definition" (definition-include #(measure-or-segment-definition :segment %))}}
"dashboard" {:fetch fetch-dashboard
- :includes {"parameters" (fn [row] {:parameters (vec (:parameters row))})
+ :includes {"parameters" dashboard-parameters
"layout" (fn [row] {:layout (dashboard-layout row)})}}
"document" {:fetch fetch-document
:includes {"layout" (fn [row] {:layout (document-layout row)})
diff --git a/src/metabase/mcp/v2/tools/parameters.clj b/src/metabase/mcp/v2/tools/parameters.clj
index b8feb5af050..8e6eb67609c 100644
--- a/src/metabase/mcp/v2/tools/parameters.clj
+++ b/src/metabase/mcp/v2/tools/parameters.clj
@@ -425,7 +425,7 @@
[:maybe [:int {:min 0 :description "Index of the first value to return (default 0) — continue a truncated response. Each page refetches from the source, which returns at most 1000 values, so narrow with `query` rather than paging to reach anything past that."}]]]])
(registry/deftool get-parameter-values
- "Fetch the valid values for one filter on a dashboard or saved question, so you filter with real values instead of guessing. Pass target (\"dashboard\" or \"question\" — the latter accepts any card id: question, model, or metric), id (numeric or 21-char entity_id), and parameter_id from get_content's `parameters` (each lists id, name, type). Values come back as [value] pairs, or [value, display_label] when the column is remapped — filter with the first element, show the second. query searches a large list rather than paging it; constraints (dashboards only) chain-filters — pass the other filters' current selections keyed by parameter id to get only the values still valid alongside them. Paged with limit (default 100, max 1000) and offset. A parameter with nothing behind it (e.g. a free-text template tag) returns no values. A column-backed date parameter answers with its range instead of a value list — {kind: \"date\", min, max, distinct_dates, accepts} — where accepts is the grammar to write a value in (\"YYYY-MM-DD\", \"YYYY-MM-DD~YYYY-MM-DD\", \"past30days\", \"thisyear\") and min/max are the column's real first and last dates to write between. constraints narrow the range as they narrow a list; query, limit and offset don't apply to it. Pair with run_saved_question, which takes these values as its `parameters`."
+ "Fetch the valid values for one filter on a dashboard or saved question, so you filter with real values instead of guessing. Pass target (\"dashboard\" or \"question\" — the latter accepts any card id: question, model, or metric), id (numeric or 21-char entity_id), and parameter_id from get_content's `parameters` (each lists id, name and type; a dashboard's parameters also show any default and value source). Values come back as [value] pairs, or [value, display_label] when the column is remapped — filter with the first element, show the second. query searches a large list rather than paging it; constraints (dashboards only) chain-filters — pass the other filters' current selections keyed by parameter id to get only the values still valid alongside them. Paged with limit (default 100, max 1000) and offset. A parameter with nothing behind it (e.g. a free-text template tag) returns no values. A column-backed date parameter answers with its range instead of a value list — {kind: \"date\", min, max, distinct_dates, accepts} — where accepts is the grammar to write a value in (\"YYYY-MM-DD\", \"YYYY-MM-DD~YYYY-MM-DD\", \"past30days\", \"thisyear\") and min/max are the column's real first and last dates to write between. constraints narrow the range as they narrow a list; query, limit and offset don't apply to it. Pair with run_saved_question, which takes these values as its `parameters`."
{:name "get_parameter_values"
:default-access :allowed
:scope metabot.scope/agent-content-read
diff --git a/test/metabase/mcp/v2/tools/content_test.clj b/test/metabase/mcp/v2/tools/content_test.clj
index 3c27aa21836..638cdd1ee5c 100644
--- a/test/metabase/mcp/v2/tools/content_test.clj
+++ b/test/metabase/mcp/v2/tools/content_test.clj
@@ -1,5 +1,6 @@
(ns metabase.mcp.v2.tools.content-test
(:require
+ [clojure.set :as set]
[clojure.string :as str]
[clojure.test :refer :all]
[clojure.walk :as walk]
@@ -13,9 +14,11 @@
[metabase.mcp.v2.tools.content :as tools.content]
[metabase.metrics.core :as metrics]
[metabase.notification.test-util :as notification.tu]
+ [metabase.parameters.schema :as parameters.schema]
[metabase.query-processor :as qp]
[metabase.test :as mt]
[metabase.util.json :as json]
+ [metabase.util.malli :as mu]
[toucan2.core :as t2]))
(set! *warn-on-reflection* true)
@@ -230,16 +233,40 @@
(is (= [{:id tab-id :name "Tab 1"}] (:tabs row)))
(testing "each parameter names the dashcards it is wired to"
(let [expected [{:id "_CAT_" :name "Category" :type "category" :dashcard_ids [dc-id]}]]
- (is (= expected (:parameters row)))
- (is (= expected
- (:parameters (content-one {:items [{:type "dashboard" :id dash-id}]
- :include ["parameters"]}))))))
+ (is (= expected (:parameters row)))))
+ (testing "the parameters include returns each stored parameter with its wired dashcard ids"
+ (is (= [{:id "_CAT_" :name "Category" :slug "category" :type "category" :dashcard_ids [dc-id]}]
+ (:parameters (content-one {:items [{:type "dashboard" :id dash-id}]
+ :include ["parameters"]})))))
(testing "one summary row per dashcard, with the card reference resolved"
(is (= [{:id dc-id :kind "card" :card {:id card-id :name "Embedded"}
:dashboard_tab_id tab-id :row 0 :col 0}]
(mapv #(select-keys % [:id :kind :card :dashboard_tab_id :row :col])
(:dashcards row))))))))))
+(deftest get-content-dashboard-parameters-include-test
+ (testing "BOT-2524: the parameters include shows the properties the concise row leaves out"
+ (mt/with-temp [:model/Dashboard {dash-id :id} {:parameters [{:id "state"
+ :name "State"
+ :slug "state"
+ :type "string/="}
+ {:id "city"
+ :name "City"
+ :slug "city"
+ :type "string/="
+ :values_query_type "list"
+ :isMultiSelect false
+ :filteringParameters ["state"]}]}]
+ (mt/with-test-user :crowberto
+ (let [city (fn [opts]
+ (-> (content-one (merge {:items [{:type "dashboard" :id dash-id}]} opts))
+ :parameters
+ second
+ (select-keys [:values_query_type :isMultiSelect :filteringParameters])))]
+ (is (= {} (city {})))
+ (is (= {:values_query_type "list" :isMultiSelect false :filteringParameters ["state"]}
+ (city {:include ["parameters"]}))))))))
+
(defn- dashcard-refs
"dashcard id -> its projected `:card` and `:series` references, for the redaction assertions."
[row]
@@ -1224,6 +1251,41 @@
(is (contains? (set (projections/catalog :metric)) "query_summary"))
(is (contains? (set (projections/catalog :document)) "content_markdown"))))
+(deftest dashboard-catalog-covers-parameter-value-sources-test
+ (testing "BOT-2524: get_content can select every key a dashboard parameter's value source config can hold"
+ (let [catalog (set (projections/catalog :dashboard))
+ config-keys (mu/map-schema-keys ::parameters.schema/values-source-config)
+ paths (into #{} (map #(str "parameters.values_source_config." (name %))) config-keys)]
+ (is (seq config-keys))
+ (is (= #{} (set/difference paths catalog))))))
+
+(deftest get-content-dashboard-parameter-value-sources-test
+ (testing "BOT-2524: a fields selection reaches into a static list and a card source"
+ (mt/with-temp [:model/Card {card-id :id} {:name "Countries"}]
+ (let [field-ref [:field (mt/id :venues :name) nil]
+ static-list {:id "country"
+ :name "Country"
+ :slug "country"
+ :type "string/="
+ :values_source_type "static-list"
+ :values_source_config {:values ["US" "CA"]}}
+ card-source {:id "region"
+ :name "Region"
+ :slug "region"
+ :type "string/="
+ :values_source_type "card"
+ :values_source_config {:card_id card-id, :value_field field-ref}}]
+ (mt/with-temp [:model/Dashboard {dash-id :id} {:parameters [static-list card-source]}]
+ (mt/with-test-user :crowberto
+ (is (=? {:parameters [{:values_source_config {:values ["US" "CA"]}}
+ {:values_source_config {:card_id card-id
+ :value_field ["field" (mt/id :venues :name) nil]}}]}
+ (content-one {:items [{:type "dashboard"
+ :id dash-id
+ :fields ["parameters.values_source_config.values"
+ "parameters.values_source_config.card_id"
+ "parameters.values_source_config.value_field"]}]})))))))))
+
(deftest get-content-subscription-fields-covers-notification-shape-test
(testing "GHY-4140: the subscription fields catalog covers the notification-backed shape, not
just the pulse shape — both are reachable under type subscription, so handlers.* must
diff --git a/test/metabase/mcp/v2/tools/dashboard_test.clj b/test/metabase/mcp/v2/tools/dashboard_test.clj
index 7b36c11eb65..a9bebcb439c 100644
--- a/test/metabase/mcp/v2/tools/dashboard_test.clj
+++ b/test/metabase/mcp/v2/tools/dashboard_test.clj
@@ -349,6 +349,27 @@
(testing "and the atomic save means nothing changed"
(is (= "Cat" (:name (param))))))))))
+(deftest response-echoes-parameter-default-and-value-source-test
+ (testing "BOT-2524: the response shows each parameter's default, required flag, and value source"
+ (mt/with-temp [:model/Dashboard dash {:name "Sales"}]
+ (let [write! (fn [ops] (tool-result (call-tool! :crowberto v2.tu/all-scopes "dashboard_write"
+ (wire {:method "update", :id (:id dash), :ops ops}))))]
+ (write! [{:op "add_parameter"
+ :parameter_id "country"
+ :name "Country"
+ :type "string/="}])
+ (is (=? {:parameters [{:id "country"
+ :default ["US"]
+ :required true
+ :values_source_type "static-list"
+ :values_source_config {:values ["US" "CA"]}}]}
+ (write! [{:op "update_parameter"
+ :parameter_id "country"
+ :default ["US"]
+ :required true
+ :values_source_type "static-list"
+ :values_source_config {:values ["US" "CA"]}}])))))))
+
(deftest unknown-card-is-a-teaching-error-test
(testing "GHY-4147: add_card referencing a card the user cannot read fails before any write"
(mt/with-temp [:model/Dashboard dash {:name "Sales"}]