Skip to content

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

Support creation and and update of a metric through mcp (#76809)

lbrdnk06d3dd8cb4a4
diff --git a/src/metabase/agent_api/api.clj b/src/metabase/agent_api/api.clj
index 8669b5eaa64..c195fe0800a 100644
--- a/src/metabase/agent_api/api.clj
+++ b/src/metabase/agent_api/api.clj
@@ -783,6 +783,147 @@
[:enum "table" "bar" "line" "pie" "scatter" "area" "row" "combo" "pivot"
"scalar" "smartscalar" "gauge" "progress" "funnel" "map" "waterfall" "sankey"])
+;;; ------------------------------------------- Card mutation helpers ------------------------------------------------
+;;
+;; `create_question`/`create_metric` and `update_question`/`update_metric` share the same
+;; permission-mirroring stack and response shape; only the card `:type`, the default display, and
+;; (for metrics) an extra query-shape validation differ. These helpers hold that common logic so the
+;; two pairs can't drift.
+
+(defn- card->base-response
+ "The card fields both the create and update tools report back."
+ [card]
+ {:id (:id card)
+ :name (:name card)
+ :display (name (:display card))
+ :collection_id (:collection_id card)
+ :collection_path (collection-path (:collection_id card))
+ :description (:description card)})
+
+(defn- create-card-response
+ "Response body for the create-card tools — the shared fields plus the saved card's URL."
+ [card]
+ (assoc (card->base-response card)
+ :url (frontend-url (channel.urls/card-path (:id card)))))
+
+(defn- update-card-response
+ "Response body for the update-card tools — the shared fields plus archived state."
+ [card]
+ (assoc (card->base-response card)
+ :archived (boolean (:archived card))))
+
+(defn- create-card-from-agent!
+ "Shared body for `create_question` / `create_metric`. Decodes the base64 `:query`, resolves the
+ target collection (absent → personal, explicit `null` → root), mirrors REST `POST /api/card/`
+ permission pre-checks, creates the card, and returns the create response.
+
+ `opts`: `:card-type` (`:question` / `:metric`), `:default-display` (used when the caller omits
+ `:display`), and optional `:validate-query!` (a metric-shape check run before the permission
+ checks).
+
+ Mirror REST `POST /api/card/` pre-checks before calling `queries/create-card!`. `create-card!`
+ itself does NOT run permissions checks; without these mirroring the REST endpoint, an LLM caller
+ could (a) save a card whose query references data the user cannot run, and (b) plant the card in a
+ collection they cannot write to.
+
+ TODO (Bryan 2026-05-20): extract REST's create-card pre-check stack into a shared
+ `metabase.queries.*` helper so REST + agent-api can't drift. This helper only dedups the two
+ agent-api create endpoints; the next person who adds a REST check will probably still miss the
+ agent side unless we dedup against REST too."
+ [{:keys [query display description visualization_settings] card-name :name :as body}
+ {:keys [card-type default-display validate-query!]}]
+ (let [dataset-query (-> query u/decode-base64 json/decode+kw)
+ ;; `nil` means the root collection, so only default to the personal collection when the
+ ;; key is absent. `(or ...)` would silently turn an explicit `null` into personal.
+ collection_id (if (contains? body :collection_id)
+ (:collection_id body)
+ (personal-collection-id))]
+ (when validate-query!
+ (validate-query! dataset-query))
+ (query-perms/check-run-permissions-for-query dataset-query)
+ (api/create-check :model/Card {:collection_id collection_id})
+ (create-card-response
+ (queries/create-card!
+ {:name card-name
+ :type card-type
+ :dataset_query dataset-query
+ :display (keyword (or display default-display))
+ :description description
+ :collection_id collection_id
+ :visualization_settings (or visualization_settings {})}
+ {:id api/*current-user-id*}))))
+
+(defn- apply-agent-card-patch!
+ "Shared body for `update_question` / `update_metric`. `card-before-update` is the card the caller
+ has already `write-check`ed. Builds the patch from `body` over the common field allowlist, mirrors
+ REST's update-card permission pre-checks, applies it, and returns the update response.
+
+ `opts` may carry `:validate-query!` — a metric-shape check run on the normalized replacement query
+ before anything is written.
+
+ TODO (Bryan 2026-05-20): see the matching TODO on `create-card-from-agent!`. The pre-check stack
+ mirrored here (collection move, run-permissions, cycle detection) is also duplicated against REST's
+ update-card path; extracting a shared `metabase.queries.*` helper is the larger fix that stops REST
+ + agent-api from drifting."
+ [card-before-update body {:keys [validate-query!]}]
+ (let [id (:id card-before-update)
+ ;; Normalize a replacement query like the REST update path so downstream helpers (metric
+ ;; validation, cycle detection, permission check) see the canonical MBQL shape regardless of
+ ;; whether the LLM sent legacy or MBQL 5.
+ new-query (when (contains? body :query)
+ (-> (:query body) u/decode-base64 json/decode+kw lib-be/normalize-query))
+ _ (when (and new-query validate-query!)
+ (validate-query! new-query))
+ raw-updates (cond-> {}
+ (contains? body :name)
+ (assoc :name (:name body))
+
+ (contains? body :description)
+ (assoc :description (:description body))
+
+ (contains? body :collection_id)
+ (assoc :collection_id (:collection_id body))
+
+ (contains? body :display)
+ (assoc :display (some-> (:display body) keyword))
+
+ (contains? body :visualization_settings)
+ (assoc :visualization_settings (:visualization_settings body))
+
+ (contains? body :archived)
+ (assoc :archived (boolean (:archived body)))
+
+ new-query
+ (assoc :dataset_query new-query))
+ ;; Set :archived_directly to mirror :archived (mark as Trash if explicitly archived). The
+ ;; REST endpoint runs this in `update-card!` on every update; we need it too so LLM-archived
+ ;; cards behave the same as UI-archived ones.
+ card-updates (api/updates-with-archived-directly card-before-update raw-updates)]
+ ;; A move (or archive that retargets the collection) requires write on BOTH the source and the
+ ;; target collection. The caller's `api/write-check :model/Card` only covered the source entity.
+ ;; Mirror the REST endpoint's `check-allowed-to-move` gate.
+ (collection/check-allowed-to-change-collection card-before-update card-updates)
+ ;; Mirror REST's `check-allowed-to-modify-query`: swapping the dataset_query requires data perms
+ ;; to run the *new* query, otherwise a user with collection write on a card can repoint it at data
+ ;; they cannot query. `queries/update-card!` does NOT run this check itself, so we run it here.
+ (when (api/column-will-change? :dataset_query card-before-update card-updates)
+ (query-perms/check-run-permissions-for-query (:dataset_query card-updates))
+ ;; Reject cycles. `lib/check-card-overwrite` throws if the new query references this card
+ ;; transitively. Mirror REST's wrapping that promotes it to HTTP 400 instead of a 500.
+ (try
+ (lib/check-card-overwrite id (:dataset_query card-updates))
+ (catch clojure.lang.ExceptionInfo e
+ ;; Don't downgrade a more specific status if the throwing fn ever starts setting one
+ ;; (e.g. a 404 for a missing card).
+ (let [data (ex-data e)]
+ (throw (ex-info (ex-message e)
+ (assoc data :status-code (or (:status-code data) 400))))))))
+ (queries/update-card! {:card-before-update card-before-update
+ :card-updates card-updates
+ :actor @api/*current-user*
+ :delete-old-dashcards? false})
+ (update-card-response (t2/select-one :model/Card :id id))))
+
(mr/def ::create-question-request
[:map
[:name ms/NonBlankString]
@@ -826,44 +967,128 @@
"Report the saved location from the response `collection_path`.")}}
[_route-params
_query-params
- {:keys [query display description visualization_settings]
- question-name :name
- :as body}
- :- ::create-question-request]
- (let [dataset-query (-> query u/decode-base64 json/decode+kw)
- ;; `nil` means the root collection, so only default to the personal collection when the
- ;; key is absent. `(or ...)` would silently turn an explicit `null` into personal.
- collection_id (if (contains? body :collection_id)
- (:collection_id body)
- (personal-collection-id))]
- ;; Mirror REST `POST /api/card/` pre-checks before calling `queries/create-card!`.
- ;; `create-card!` itself does NOT run permissions checks; without these mirroring the
- ;; REST endpoint, an LLM caller could (a) save a card whose query references data the
- ;; user cannot run, and (b) plant the card in a collection they cannot write to.
- ;; (REST also calls `check-if-card-can-be-saved`, which only fires for `card-type :metric`;
- ;; this endpoint always creates a question, so we omit it.)
- ;;
- ;; TODO (Bryan 2026-05-20): extract REST's create-card pre-check stack into a shared
- ;; `metabase.queries.*` helper so REST + agent-api can't drift. Branch review caught
- ;; this gap; the next person who adds a REST check will probably miss the agent side
- ;; again unless we dedup.
- (query-perms/check-run-permissions-for-query dataset-query)
- (api/create-check :model/Card {:collection_id collection_id})
- (let [card (queries/create-card!
- {:name question-name
- :dataset_query dataset-query
- :display (keyword (or display "table"))
- :description description
- :collection_id collection_id
- :visualization_settings (or visualization_settings {})}
- {:id api/*current-user-id*})]
- {:id (:id card)
- :name (:name card)
- :url (frontend-url (channel.urls/card-path (:id card)))
- :display (name (:display card))
- :collection_id (:collection_id card)
- :collection_path (collection-path (:collection_id card))
- :description (:description card)})))
+ body :- ::create-question-request]
+ ;; REST also calls `check-if-card-can-be-saved`, which only fires for `card-type :metric`; this
+ ;; endpoint always creates a question, so no `:validate-query!` is passed.
+ (create-card-from-agent! body {:card-type :question, :default-display "table"}))
+
+;;; -------------------------------------------------- Create Metric -------------------------------------------------
+
+(mr/def ::create-metric-request
+ [:map
+ [:name ms/NonBlankString]
+ [:query ms/NonBlankString]
+ [:display {:optional true} [:maybe ::card-display]]
+ [:description {:optional true} [:maybe :string]]
+ [:collection_id {:optional true} [:maybe ms/PositiveInt]]
+ [:visualization_settings {:optional true} [:maybe :map]]])
+
+(mr/def ::create-metric-response
+ [:map
+ [:id ms/PositiveInt]
+ [:name ms/NonBlankString]
+ [:url :string]
+ [:display :string]
+ [:collection_id [:maybe ms/PositiveInt]]
+ [:collection_path :string]
+ [:description [:maybe :string]]])
+
+(defn- check-metric-query-can-be-saved!
+ "Throw a 400 unless `dataset-query` is a valid metric definition. Mirrors REST's
+ `check-if-card-can-be-saved` for `:metric` cards: a metric needs a single stage, exactly one
+ aggregation, and at most one date/datetime breakout (see `lib/can-run-method`). The base64
+ payload stored by `construct_query` is stripped of its metadata provider, so re-hydrate one
+ before calling `lib/can-save?` (its breakout type-check reads field metadata)."
+ [dataset-query]
+ (let [mp (lib-be/application-database-metadata-provider (:database dataset-query))
+ query (lib/query mp dataset-query)]
+ (when-not (lib/can-save? query :metric)
+ (throw (ex-info (str "This query can't be saved as a metric. A metric needs exactly one "
+ "aggregation and at most one date/datetime grouping. Construct a query "
+ "with a single summarize (e.g. count, sum) before saving it as a metric.")
+ {:status-code 400})))))
+
+(api.macros/defendpoint :post "/v1/metric" :- ::create-metric-response
+ "Save a previously constructed query as a named metric.
+
+ A metric is a reusable aggregation (a `Card` of type `metric`): the underlying query must have
+ exactly one aggregation and at most one date/datetime grouping. The `query` parameter accepts a
+ `query_handle` (UUID) returned by `construct_query`, or a base64-encoded MBQL string. MCP callers
+ should always use the handle.
+ Optionally specify display type, description, collection, and visualization settings.
+ If `collection_id` is omitted the metric is saved to the caller's personal collection.
+ Pass an explicit `null` to save it to the root collection.
+ The response `collection_path` is the saved location."
+ {:scope metabot/agent-metric-create
+ :tool {:name "create_metric"
+ :description (str "Save a query as a reusable metric in Metabase. "
+ "Pass the `query_handle` returned by `construct_query`. "
+ "The query must have exactly one aggregation (e.g. count, sum, average) "
+ "and at most one date/datetime grouping — build it with `construct_query` first. "
+ "Optionally set display type, description, and target collection. "
+ "If you omit collection_id it's saved to the user's personal collection; "
+ "pass an explicit null to save it to the root collection. "
+ "Report the saved location from the response `collection_path`.")}}
+ [_route-params
+ _query-params
+ body :- ::create-metric-request]
+ (create-card-from-agent! body {:card-type :metric
+ :default-display "scalar"
+ :validate-query! check-metric-query-can-be-saved!}))
+
+;;; -------------------------------------------------- Update Metric -------------------------------------------------
+
+(mr/def ::update-metric-request
+ "Patch shape for `update_metric`. Every field is optional; only the fields the caller
+ passes are changed. `:query` accepts a base64-encoded MBQL string (or query_handle UUID
+ resolved upstream in the MCP layer) and must still describe a valid metric."
+ [:map
+ [:name {:optional true} [:maybe ms/NonBlankString]]
+ [:description {:optional true} [:maybe :string]]
+ [:collection_id {:optional true} [:maybe ms/PositiveInt]]
+ [:display {:optional true} [:maybe ::card-display]]
+ [:visualization_settings {:optional true} [:maybe :map]]
+ [:archived {:optional true} [:maybe :boolean]]
+ [:query {:optional true} [:maybe ms/NonBlankString]]])
+
+(mr/def ::update-metric-response
+ "Returned by `update_metric` - the fields the LLM is most likely to want to read back
+ after an update. Excludes the full dataset_query, which the caller can re-fetch via
+ `read_resource` if needed."
+ [:map
+ [:id ms/PositiveInt]
+ [:name ms/NonBlankString]
+ [:display :string]
+ [:collection_id [:maybe ms/PositiveInt]]
+ [:collection_path :string]
+ [:description [:maybe :string]]
+ [:archived :boolean]])
+
+(api.macros/defendpoint :put "/v1/metric/:id" :- ::update-metric-response
+ "Update a saved metric. Patch semantics - only fields that you pass are changed.
+
+ Set `collection_id` to move the metric to a different collection. Set `archived: true` to archive.
+ Pass `query` (a query_handle from construct_query, or a base64 MBQL string) to replace the underlying
+ query; the replacement must still be a valid metric (exactly one aggregation, at most one
+ date/datetime grouping). The target card must be a metric — use `update_question` for questions."
+ {:scope metabot/agent-metric-update
+ :tool {:name "update_metric"
+ :description (str "Update a saved metric. Patch semantics - only fields you pass are changed. "
+ "To move a metric to a different collection, set collection_id. "
+ "To archive, set archived true. To replace the underlying query, pass query "
+ "(a query_handle from construct_query) - it must still have exactly one "
+ "aggregation and at most one date/datetime grouping. The target must be a "
+ "metric; use update_question for regular questions.")}}
+ [{:keys [id]} :- [:map [:id ms/PositiveInt]]
+ _query-params
+ body :- ::update-metric-request]
+ (let [card-before-update (api/write-check :model/Card id)]
+ ;; This is the metric endpoint: refuse to touch questions/models so an LLM can't silently force a
+ ;; non-metric card's query through the metric-shape validation (and vice-versa via update_question).
+ (api/check-400 (= :metric (:type card-before-update))
+ (str "Card " id " is not a metric. Use update_question to update questions."))
+ (apply-agent-card-patch! card-before-update body
+ {:validate-query! check-metric-query-can-be-saved!})))
;;; ------------------------------------------------- Update Question ------------------------------------------------
@@ -909,77 +1134,7 @@
[{:keys [id]} :- [:map [:id ms/PositiveInt]]
_query-params
body :- ::update-question-request]
- (let [card-before-update (api/write-check :model/Card id)
- raw-updates (cond-> {}
- (contains? body :name)
- (assoc :name (:name body))
-
- (contains? body :description)
- (assoc :description (:description body))
-
- (contains? body :collection_id)
- (assoc :collection_id (:collection_id body))
-
- (contains? body :display)
- (assoc :display (some-> (:display body) keyword))
-
- (contains? body :visualization_settings)
- (assoc :visualization_settings (:visualization_settings body))
-
- (contains? body :archived)
- (assoc :archived (boolean (:archived body)))
-
- (contains? body :query)
- (assoc :dataset_query
- ;; Normalize like the REST update path so downstream
- ;; helpers (cycle detection, permission check) see the
- ;; canonical MBQL shape regardless of whether the LLM
- ;; sent legacy or MBQL 5.
- (-> (:query body)
- u/decode-base64
- json/decode+kw
- lib-be/normalize-query)))
- ;; Set :archived_directly to mirror :archived (mark as Trash if explicitly archived).
- ;; The REST endpoint runs this in `update-card!` on every update; we need it too so
- ;; LLM-archived cards behave the same as UI-archived ones.
- card-updates (api/updates-with-archived-directly card-before-update raw-updates)
- ;; A move (or archive that retargets the collection) requires write on BOTH the source
- ;; and the target collection. `api/write-check :model/Card` above only covered the source
- ;; entity. Mirror the REST endpoint's `check-allowed-to-move` gate.
- _ (collection/check-allowed-to-change-collection card-before-update card-updates)
- ;; Mirror REST's `check-allowed-to-modify-query`: swapping the dataset_query requires
- ;; data perms to run the *new* query, otherwise a user with collection write on a card
- ;; can repoint it at data they cannot query. `queries/update-card!` does NOT run this
- ;; check itself, so we have to run it before calling in.
- ;;
- ;; TODO (Bryan 2026-05-20): see matching TODO above `create_question`. Extract REST's
- ;; update-card pre-check stack so REST + agent-api can't drift; this single check is
- ;; only the most recent gap we noticed.
- _ (when (api/column-will-change? :dataset_query card-before-update card-updates)
- (query-perms/check-run-permissions-for-query (:dataset_query card-updates))
- ;; Reject cycles. `lib/check-card-overwrite` throws if the new query
- ;; references this card transitively. Mirror REST's wrapping that
- ;; promotes it to HTTP 400 instead of a 500.
- (try
- (lib/check-card-overwrite id (:dataset_query card-updates))
- (catch clojure.lang.ExceptionInfo e
- ;; Don't downgrade a more specific status if the throwing fn
- ;; ever starts setting one (e.g. a 404 for a missing card).
- (let [data (ex-data e)]
- (throw (ex-info (ex-message e)
- (assoc data :status-code (or (:status-code data) 400))))))))
- _ (queries/update-card! {:card-before-update card-before-update
- :card-updates card-updates
- :actor @api/*current-user*
- :delete-old-dashcards? false})
- updated (t2/select-one :model/Card :id id)]
- {:id (:id updated)
- :name (:name updated)
- :display (clojure.core/name (:display updated))
- :collection_id (:collection_id updated)
- :collection_path (collection-path (:collection_id updated))
- :description (:description updated)
- :archived (boolean (:archived updated))}))
+ (apply-agent-card-patch! (api/write-check :model/Card id) body nil))
;;; ------------------------------------------------ Execute Question -----------------------------------------------
diff --git a/src/metabase/mcp/README.md b/src/metabase/mcp/README.md
index 7ad69c03126..c46408e03dc 100644
--- a/src/metabase/mcp/README.md
+++ b/src/metabase/mcp/README.md
@@ -64,6 +64,8 @@ Access tokens are scoped to limit what tools a client can use:
| `agent:question:create` | `create_question` |
| `agent:question:update` | `update_question` (also covers "move card to collection") |
| `agent:question:execute` | `execute_question` |
+| `agent:metric:create` | `create_metric` |
+| `agent:metric:update` | `update_metric` (also covers "move metric to collection") |
| `agent:dashboard:create` | `create_dashboard` |
| `agent:dashboard:update` | `update_dashboard` |
| `agent:collection:create` | `create_collection` |
@@ -104,6 +106,8 @@ The MCP server exposes these tools, dynamically generated from the Agent API end
| Tool | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `create_metric` | Save a query as a reusable metric. Accepts a `query_handle` from `construct_query`. The query needs one aggregation and at most one date grouping. |
+| `update_metric` | Update a saved metric. Patch semantics. Setting `collection_id` moves it; setting `archived` archives it. A replacement `query` must still be a valid metric. |
| `create_question` | Save a query as a named question (card). Accepts a `query_handle` from `construct_query` (MBQL) or `construct_native_query` (native SQL). Saving native requires native-query DB permission. |
| `update_question` | Update a saved question. Patch semantics. Setting `collection_id` moves the card. Setting `archived` archives it. Replacing the query accepts a `construct_query` or `construct_native_query` handle. |
| `create_dashboard` | Create a new dashboard, optionally populated with saved questions (auto-positioned on the grid). |
diff --git a/src/metabase/mcp/tools.clj b/src/metabase/mcp/tools.clj
index 7e61432e03d..63f052394fa 100644
--- a/src/metabase/mcp/tools.clj
+++ b/src/metabase/mcp/tools.clj
@@ -330,7 +330,7 @@
;; handle, but it's a UI tool that resolves the handle itself (see `metabase.mcp.resources`) and
;; never reaches this dispatch path, so it's intentionally absent here.
(def ^:private tools-accepting-query-handle
- #{"execute_query" "query" "create_question" "update_question"})
+ #{"execute_query" "query" "create_question" "update_question" "create_metric" "update_metric"})
;; Tools whose 200 body is `{:query base64}` and gets stored as a handle, returning `{:query_handle}`.
;; `construct_query` (MBQL) and `construct_native_query` (native SQL) both follow this contract.
diff --git a/src/metabase/metabot/core.clj b/src/metabase/metabot/core.clj
index 8eb57f5c7fd..307dd415acc 100644
--- a/src/metabase/metabot/core.clj
+++ b/src/metabase/metabot/core.clj
@@ -21,6 +21,8 @@
agent-question-create
agent-question-execute
agent-question-update
+ agent-metric-create
+ agent-metric-update
agent-resource-read
agent-search
agent-sql-construct
diff --git a/src/metabase/metabot/scope.clj b/src/metabase/metabot/scope.clj
index 19a0c10e0bd..df9d18c3d54 100644
--- a/src/metabase/metabot/scope.clj
+++ b/src/metabase/metabot/scope.clj
@@ -44,6 +44,12 @@
(api-scope/defscope agent-question-execute "agent:question:execute"
(deferred-tru "Run saved questions"))
+;; Metric (saved metric cards via Agent API)
+(api-scope/defscope agent-metric-create "agent:metric:create"
+ (deferred-tru "Create metrics"))
+(api-scope/defscope agent-metric-update "agent:metric:update"
+ (deferred-tru "Update metrics"))
+
;; Transforms
(api-scope/defscope agent-transforms-read "agent:transforms:read"
(deferred-tru "View transforms"))
@@ -171,7 +177,7 @@
"Map from metabot permission type to the wildcard scope strings granted when
that permission is `:yes`."
{:permission/metabot-sql-generation #{"agent:sql:*" "agent:transforms:*" "agent:snippets:*"}
- :permission/metabot-nlq #{"agent:notebook:*" "agent:query:*" "agent:question:*"}
+ :permission/metabot-nlq #{"agent:notebook:*" "agent:query:*" "agent:question:*" "agent:metric:*"}
:permission/metabot-other-tools #{"agent:viz:*" "agent:dashboard:*" "agent:document:*" "agent:alert:*"
"agent:collection:*"}})
diff --git a/test/metabase/agent_api/api_test.clj b/test/metabase/agent_api/api_test.clj
index 9b1071a7030..8021af3c6e1 100644
--- a/test/metabase/agent_api/api_test.clj
+++ b/test/metabase/agent_api/api_test.clj
@@ -785,6 +785,199 @@
(is (= "Visible Parent / Leaf Coll" (:collection_path create-resp)))
(t2/delete! :model/Card :id (:id create-resp)))))))
+;;; ------------------------------------------------ Create Metric Tests --------------------------------------------
+
+(deftest create-metric-test
+ (testing "Omitting collection_id saves a metric to the caller's personal collection, not root"
+ (let [personal-id (:id (collection/user->personal-collection (mt/user->id :rasta)))
+ personal-name (collection/user->personal-collection-name (mt/user->id :rasta) :user)
+ construct-resp (mt/user-http-request :rasta :post 200 "agent/v2/construct-query"
+ {:query (orders-query :aggregation [["count" {}]])})
+ create-resp (mt/user-http-request :rasta :post 200 "agent/v1/metric"
+ {:name "Agent Test Metric"
+ :query (:query construct-resp)})]
+ (is (=? {:id pos?
+ :name "Agent Test Metric"
+ :display "scalar"
+ :collection_id personal-id
+ :collection_path personal-name
+ :description nil}
+ create-resp))
+ (is (=? {:type :metric} (t2/select-one :model/Card :id (:id create-resp))))
+ (t2/delete! :model/Card :id (:id create-resp))))
+ (testing "Creates a metric with optional fields"
+ (mt/with-temp [:model/Collection {coll-id :id} {:name "Agent Metric Collection"}]
+ (let [construct-resp (mt/user-http-request :rasta :post 200 "agent/v2/construct-query"
+ {:query (orders-query :aggregation [["count" {}]])})
+ create-resp (mt/user-http-request :rasta :post 200 "agent/v1/metric"
+ {:name "Agent Metric With Options"
+ :query (:query construct-resp)
+ :display "line"
+ :description "A test metric"
+ :collection_id coll-id})]
+ (is (=? {:id pos?
+ :name "Agent Metric With Options"
+ :display "line"
+ :collection_id coll-id
+ :collection_path "Our analytics / Agent Metric Collection"
+ :description "A test metric"}
+ create-resp))
+ (t2/delete! :model/Card :id (:id create-resp))))))
+
+(deftest create-metric-rejects-invalid-metric-test
+ (testing "Returns 400 when the query is not a valid metric (no aggregation)"
+ (let [construct-resp (mt/user-http-request :rasta :post 200 "agent/v2/construct-query"
+ {:query (orders-query :limit 10)})]
+ (is (str/includes?
+ (mt/user-http-request :rasta :post 400 "agent/v1/metric"
+ {:name "Not A Metric"
+ :query (:query construct-resp)})
+ "metric")))))
+
+(deftest create-metric-permission-checks-test
+ (testing "Returns 403 when caller cannot run the proposed query"
+ (mt/with-restored-data-perms!
+ (mt/with-non-admin-groups-no-root-collection-perms
+ (mt/with-temp [:model/Collection {writable-id :id} {:name "Writable For Create-Metric"}]
+ (perms/grant-collection-readwrite-permissions! (perms-group/all-users) writable-id)
+ (data-perms/set-database-permission! (perms-group/all-users) (mt/id) :perms/view-data :blocked)
+ (let [construct-resp (mt/user-http-request :crowberto :post 200 "agent/v2/construct-query"
+ {:query (orders-query :aggregation [["count" {}]])})]
+ (mt/user-http-request :rasta :post 403 "agent/v1/metric"
+ {:name "Should Not Save"
+ :query (:query construct-resp)
+ :collection_id writable-id}))))))
+ (testing "Returns 403 when caller cannot write to target collection"
+ (mt/with-non-admin-groups-no-root-collection-perms
+ (mt/with-temp [:model/Collection {locked-id :id} {:name "Locked For Create-Metric"}]
+ (let [construct-resp (mt/user-http-request :rasta :post 200 "agent/v2/construct-query"
+ {:query (orders-query :aggregation [["count" {}]])})]
+ (mt/user-http-request :rasta :post 403 "agent/v1/metric"
+ {:name "Should Not Save"
+ :query (:query construct-resp)
+ :collection_id locked-id}))))))
+
+(deftest create-metric-explicit-null-collection-test
+ (testing "An explicit null collection_id saves the metric to the root collection, not the personal default"
+ (let [construct-resp (mt/user-http-request :rasta :post 200 "agent/v2/construct-query"
+ {:query (orders-query :aggregation [["count" {}]])})
+ create-resp (mt/user-http-request :rasta :post 200 "agent/v1/metric"
+ {:name "Agent Root Metric"
+ :query (:query construct-resp)
+ :collection_id nil})]
+ (is (=? {:collection_id nil
+ :collection_path "Our analytics"}
+ create-resp))
+ (t2/delete! :model/Card :id (:id create-resp)))))
+
+;;; ------------------------------------------------ Update Metric Tests --------------------------------------------
+
+(deftest update-metric-patch-fields-test
+ (testing "Patches simple fields (name, description) on a metric"
+ (mt/with-temp [:model/Card {card-id :id} {:name "Agent Update Metric Original"
+ :type :metric
+ :dataset_query (orders-count-query)
+ :display :scalar}]
+ (let [resp (mt/user-http-request :rasta :put 200 (str "agent/v1/metric/" card-id)
+ {:name "Renamed Metric"
+ :description "Set by agent"})]
+ (is (=? {:id card-id
+ :name "Renamed Metric"
+ :description "Set by agent"
+ :archived false}
+ resp)))
+ (is (= "Renamed Metric" (t2/select-one-fn :name :model/Card :id card-id))))))
+
+(deftest update-metric-move-test
+ (testing "Moving a metric sets collection_id"
+ (mt/with-temp [:model/Collection {dest-coll-id :id} {:name "Agent Metric Move Dest"}
+ :model/Card {card-id :id} {:name "Metric To Move"
+ :type :metric
+ :dataset_query (orders-count-query)
+ :display :scalar}]
+ (let [resp (mt/user-http-request :rasta :put 200 (str "agent/v1/metric/" card-id)
+ {:collection_id dest-coll-id})]
+ (is (=? {:collection_id dest-coll-id
+ :collection_path "Our analytics / Agent Metric Move Dest"}
+ resp)))
+ (is (= dest-coll-id (t2/select-one-fn :collection_id :model/Card :id card-id))))))
+
+(deftest update-metric-archive-test
+ (testing "Archiving a metric also sets :archived_directly so it lands in the Trash"
+ (mt/with-temp [:model/Card {card-id :id} {:name "Metric To Archive"
+ :type :metric
+ :dataset_query (orders-count-query)
+ :display :scalar}]
+ (let [resp (mt/user-http-request :rasta :put 200 (str "agent/v1/metric/" card-id)
+ {:archived true})]
+ (is (true? (:archived resp))))
+ (is (true? (t2/select-one-fn :archived :model/Card :id card-id)))
+ (is (true? (t2/select-one-fn :archived_directly :model/Card :id card-id))))))
+
+(deftest update-metric-replace-query-test
+ (testing "Replacing the underlying query via :query keeps a valid metric"
+ (mt/with-temp [:model/Card {card-id :id} {:name "Metric To Re-query"
+ :type :metric
+ :dataset_query (orders-count-query)
+ :display :scalar}]
+ (let [products-id (mt/id :products)
+ construct (mt/user-http-request :rasta :post 200 "agent/v2/construct-query"
+ {:query {:lib/type "mbql/query"
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table [(db-name) "PUBLIC" "PRODUCTS"]
+ :aggregation [["count" {}]]}]}})
+ _resp (mt/user-http-request :rasta :put 200 (str "agent/v1/metric/" card-id)
+ {:query (:query construct)})
+ persisted (t2/select-one-fn :dataset_query :model/Card :id card-id)
+ source-table (some :source-table (:stages persisted))]
+ (is (some? persisted))
+ (is (= products-id source-table)
+ (str "Expected persisted dataset_query :source-table to be the products table id "
+ products-id ", got " source-table))))))
+
+(deftest update-metric-rejects-non-metric-query-test
+ (testing "Returns 400 when a replacement query is not a valid metric (no aggregation)"
+ (mt/with-temp [:model/Card {card-id :id} {:name "Metric With Bad Requery"
+ :type :metric
+ :dataset_query (orders-count-query)
+ :display :scalar}]
+ (let [construct (mt/user-http-request :rasta :post 200 "agent/v2/construct-query"
+ {:query (orders-query :limit 5)})]
+ (is (str/includes?
+ (mt/user-http-request :rasta :put 400 (str "agent/v1/metric/" card-id)
+ {:query (:query construct)})
+ "metric"))
+ ;; query untouched after the rejected update — still the original count aggregation
+ (is (seq (:aggregation (first (:stages (t2/select-one-fn :dataset_query :model/Card :id card-id))))))))))
+
+(deftest update-metric-rejects-non-metric-card-test
+ (testing "Returns 400 when the target card is not a metric"
+ (mt/with-temp [:model/Card {card-id :id} {:name "Just A Question"
+ :type :question
+ :dataset_query (orders-count-query)
+ :display :table}]
+ (is (str/includes?
+ (mt/user-http-request :rasta :put 400 (str "agent/v1/metric/" card-id)
+ {:name "Rename Attempt"})
+ "not a metric")))))
+
+(deftest update-metric-not-found-test
+ (testing "Returns 404 when metric does not exist"
+ (mt/user-http-request :rasta :put 404 "agent/v1/metric/999999"
+ {:name "doesn't matter"})))
+
+(deftest update-metric-write-perm-test
+ (testing "Returns 403 when caller lacks write access on the metric"
+ (mt/with-non-admin-groups-no-root-collection-perms
+ (mt/with-temp [:model/Collection {locked-coll-id :id} {:name "Locked Metric Coll"}
+ :model/Card {card-id :id} {:name "Hidden Metric"
+ :type :metric
+ :dataset_query (orders-count-query)
+ :display :scalar
+ :collection_id locked-coll-id}]
+ (mt/user-http-request :rasta :put 403 (str "agent/v1/metric/" card-id)
+ {:name "Forbidden Rename"})))))
+
;;; ----------------------------------------------- Create Dashboard Tests ------------------------------------------
(deftest create-dashboard-test
diff --git a/test/metabase/mcp/api_test.clj b/test/metabase/mcp/api_test.clj
index 90b891502d1..463999cc335 100644
--- a/test/metabase/mcp/api_test.clj
+++ b/test/metabase/mcp/api_test.clj
@@ -274,6 +274,7 @@
"construct_native_query"
"create_collection"
"create_dashboard"
+ "create_metric"
"create_question"
"execute_query"
"execute_question"
@@ -283,6 +284,7 @@
"render_drill_through"
"search"
"update_dashboard"
+ "update_metric"
"update_question"
"visualize_query"})
@@ -662,8 +664,8 @@
invocation check."
#{"search" "construct_query" "construct_native_query" "query" "execute_query" "execute_sql"
"read_resource"
- "create_question" "execute_question" "create_dashboard"
- "update_question" "update_dashboard" "create_collection"})
+ "create_question" "execute_question" "create_metric" "create_dashboard"
+ "update_question" "update_metric" "update_dashboard" "create_collection"})
(deftest tools-call-smoke-test-covers-all-agent-api-backed-tools-test
(testing "every Agent API-backed tool is exercised by the smoke test"
@@ -686,9 +688,15 @@
:stages [{:lib/type "mbql.stage/mbql"
:source-table [db-name "PUBLIC" "ORDERS"]
:limit 5}]}
+ ;; A metric needs exactly one aggregation — `create_metric` rejects a plain query.
+ metric-query {:lib/type "mbql/query"
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table [db-name "PUBLIC" "ORDERS"]
+ :aggregation [["count" {}]]}]}
;; Track write-tool outputs in atoms so the `finally` cleanup runs even if an
;; assertion in `call-tool` fails partway through the sequence.
question-id (atom nil)
+ metric-id (atom nil)
dash-id (atom nil)
coll-id (atom nil)]
(try
@@ -725,6 +733,15 @@
_ (call-tool session-id "update_question"
{:id (:id question-data)
:description "Smoke updated description"})
+ metric-handle (call-tool session-id "construct_query" {:query metric-query})
+ metric-data (call-tool session-id "create_metric"
+ {:name "Smoke Metric Card"
+ :query_handle (:query_handle metric-handle)})
+ _ (reset! metric-id (:id metric-data))
+ _ (is (= "scalar" (:display metric-data)))
+ _ (call-tool session-id "update_metric"
+ {:id (:id metric-data)
+ :description "Smoke updated metric"})
_ (call-tool session-id "execute_question"
{:id (:id question-data)})
dash-data (call-tool session-id "create_dashboard"
@@ -740,6 +757,7 @@
(reset! coll-id (:id coll-data)))
(finally
(when-let [qid @question-id] (t2/delete! :model/Card :id qid))
+ (when-let [mid @metric-id] (t2/delete! :model/Card :id mid))
(when-let [did @dash-id] (t2/delete! :model/Dashboard :id did))
(when-let [cid @coll-id] (t2/delete! :model/Collection :id cid))))))))))
diff --git a/test/metabase/metabot/scope_test.clj b/test/metabase/metabot/scope_test.clj
index 4e6fccc7b36..6471872431d 100644
--- a/test/metabase/metabot/scope_test.clj
+++ b/test/metabase/metabot/scope_test.clj
@@ -119,6 +119,8 @@
(deftest ^:parallel mcp-write-scopes-registered-test
(testing "new MCP write-tool scopes are registered"
(is (api-scope/registered-scope? "agent:question:update"))
+ (is (api-scope/registered-scope? "agent:metric:create"))
+ (is (api-scope/registered-scope? "agent:metric:update"))
(is (api-scope/registered-scope? "agent:dashboard:update"))
(is (api-scope/registered-scope? "agent:collection:create"))
(is (api-scope/registered-scope? "agent:sql:execute"))))
@@ -126,6 +128,8 @@
(deftest ^:parallel mcp-write-scopes-defscope-vars-test
(testing "new scope vars resolve to their string"
(is (= "agent:question:update" scope/agent-question-update))
+ (is (= "agent:metric:create" scope/agent-metric-create))
+ (is (= "agent:metric:update" scope/agent-metric-update))
(is (= "agent:dashboard:update" scope/agent-dashboard-update))
(is (= "agent:collection:create" scope/agent-collection-create))
(is (= "agent:sql:execute" scope/agent-sql-execute))))
@@ -134,6 +138,12 @@
(testing "agent:question:update granted via metabot-nlq wildcard"
(let [scopes (scope/user-metabot-perms->scopes {:permission/metabot-nlq :yes})]
(is (api-scope/scope-matches? scopes "agent:question:update"))))
+ (testing "agent:metric:create granted via metabot-nlq wildcard"
+ (let [scopes (scope/user-metabot-perms->scopes {:permission/metabot-nlq :yes})]
+ (is (api-scope/scope-matches? scopes "agent:metric:create"))))
+ (testing "agent:metric:update granted via metabot-nlq wildcard"
+ (let [scopes (scope/user-metabot-perms->scopes {:permission/metabot-nlq :yes})]
+ (is (api-scope/scope-matches? scopes "agent:metric:update"))))
(testing "agent:dashboard:update granted via metabot-other-tools wildcard"
(let [scopes (scope/user-metabot-perms->scopes {:permission/metabot-other-tools :yes})]
(is (api-scope/scope-matches? scopes "agent:dashboard:update"))))