Skip to content

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

Mention archival and soft deletion in MCP metric update API (#77525)

lbrdnk87f05145194a
diff --git a/src/metabase/agent_api/api.clj b/src/metabase/agent_api/api.clj
index 9c319bb738e..c896100c99d 100644
--- a/src/metabase/agent_api/api.clj
+++ b/src/metabase/agent_api/api.clj
@@ -1068,6 +1068,8 @@
"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.
+ Archiving is a soft delete - there is no delete endpoint. It can be reversed by setting
+ `archived: false`.
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."
@@ -1075,7 +1077,9 @@
: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 "
+ "Archiving (archived true) is a soft delete - use it when asked to "
+ "delete or remove a metric; set archived false to restore. "
+ "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.")}}
diff --git a/src/metabase/mcp/README.md b/src/metabase/mcp/README.md
index c46408e03dc..cc0ebc796e0 100644
--- a/src/metabase/mcp/README.md
+++ b/src/metabase/mcp/README.md
@@ -65,7 +65,7 @@ Access tokens are scoped to limit what tools a client can use:
| `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:metric:update` | `update_metric` (also covers "move metric to collection" and archiving) |
| `agent:dashboard:create` | `create_dashboard` |
| `agent:dashboard:update` | `update_dashboard` |
| `agent:collection:create` | `create_collection` |
@@ -107,7 +107,7 @@ 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. |
+| `update_metric` | Update a saved metric. Patch semantics. Setting `collection_id` moves it; setting `archived: true` archives it — a reversible soft delete, used when asked to delete a metric. 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/test/metabase/agent_api/api_test.clj b/test/metabase/agent_api/api_test.clj
index 12f7f1c42a8..c7188ee92da 100644
--- a/test/metabase/agent_api/api_test.clj
+++ b/test/metabase/agent_api/api_test.clj
@@ -920,7 +920,13 @@
{: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))))))
+ (is (true? (t2/select-one-fn :archived_directly :model/Card :id card-id)))
+ (testing "archival is a soft delete: archived: false reverses it"
+ (let [resp (mt/user-http-request :rasta :put 200 (str "agent/v1/metric/" card-id)
+ {:archived false})]
+ (is (false? (:archived resp))))
+ (is (false? (t2/select-one-fn :archived :model/Card :id card-id)))
+ (is (false? (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"