Skip to content

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

MCP notes on archiving questions and dashboards (#77569)

Chris Truter4d04a9743c65
diff --git a/src/metabase/agent_api/api.clj b/src/metabase/agent_api/api.clj
index f7e071bb790..bf8c9978fb5 100644
--- a/src/metabase/agent_api/api.clj
+++ b/src/metabase/agent_api/api.clj
@@ -1113,6 +1113,8 @@
"Update a saved question (card). Patch semantics - only fields that you pass are changed.
Set `collection_id` to move the card 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 construct_native_query, or a base64 query
string) to replace the underlying query. Replacing it with a native (raw SQL) query requires
native-query permission on the target database."
@@ -1120,7 +1122,9 @@
:tool {:name "update_question"
:description (str "Update a saved question (card). Patch semantics - only fields you pass are changed. "
"To move a card 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 question; set archived false to restore. "
+ "To replace the underlying query, pass query "
"(a query_handle from construct_query or construct_native_query).")}}
[{:keys [id]} :- [:map [:id ms/PositiveInt]]
_query-params
@@ -1519,15 +1523,18 @@
(api.macros/defendpoint :put "/v1/dashboard/:id" :- ::update-dashboard-response
"Update a dashboard. Patch semantics - only fields you pass are changed.
- Metadata: `name`, `description`, `collection_id`, `archived`. Dashcard mutations
- are submitted under `dashcards` as a list of
+ Metadata: `name`, `description`, `collection_id`, `archived`. Archiving is a soft delete - there
+ is no delete endpoint. It can be reversed by setting `archived: false`.
+ Dashcard mutations are submitted under `dashcards` as a list of
`{action: add|add_heading|add_text|update_text|remove|move, ...}` entries applied in
order. `add` requires `card_id`; `add_heading` and `add_text` require `text` (Markdown
for text cards); `update_text`, `remove`, and `move` require `dashcard_id`."
{:scope metabot/agent-dashboard-update
:tool {:name "update_dashboard"
:description (str "Update a dashboard. Patch semantics - only fields you pass are changed. "
- "Set collection_id to move it. Set archived true to archive. "
+ "Set collection_id to move it. "
+ "Archiving (archived true) is a soft delete - use it when asked to "
+ "delete or remove a dashboard; set archived false to restore. "
"Use dashcards to add, remove, or move cards: "
"[{\"action\":\"add\",\"card_id\":42},{\"action\":\"remove\",\"dashcard_id\":101}]. "
"add_heading adds a full-width section heading and add_text adds a "
diff --git a/src/metabase/mcp/README.md b/src/metabase/mcp/README.md
index cc0ebc796e0..ce883a7397d 100644
--- a/src/metabase/mcp/README.md
+++ b/src/metabase/mcp/README.md
@@ -62,12 +62,12 @@ Access tokens are scoped to limit what tools a client can use:
| `agent:sql:construct` | `construct_native_query` |
| `agent:sql:execute` | `execute_sql` |
| `agent:question:create` | `create_question` |
-| `agent:question:update` | `update_question` (also covers "move card to collection") |
+| `agent:question:update` | `update_question` (also covers "move card to collection" and archiving) |
| `agent:question:execute` | `execute_question` |
| `agent:metric:create` | `create_metric` |
| `agent:metric:update` | `update_metric` (also covers "move metric to collection" and archiving) |
| `agent:dashboard:create` | `create_dashboard` |
-| `agent:dashboard:update` | `update_dashboard` |
+| `agent:dashboard:update` | `update_dashboard` (also covers archiving) |
| `agent:collection:create` | `create_collection` |
Wildcard patterns (e.g. `agent:*`) match any scope with that prefix.
@@ -109,9 +109,9 @@ The MCP server exposes these tools, dynamically generated from the Agent API end
| `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: 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. |
+| `update_question` | Update a saved question. Patch semantics. Setting `collection_id` moves the card. Setting `archived: true` archives it — a reversible soft delete, used when asked to delete a question. 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). |
-| `update_dashboard` | Update a dashboard's metadata (name, description, collection, archived). |
+| `update_dashboard` | Update a dashboard's metadata (name, description, collection, archived — a reversible soft delete, used when asked to delete a dashboard). |
| `create_collection` | Create a new collection. Optionally nested under a `parent_collection_id`. |
Query results are limited to 200 rows per request. When more rows are available, the response includes a
diff --git a/test/metabase/agent_api/api_test.clj b/test/metabase/agent_api/api_test.clj
index b94a4fdb6c3..c450dd3346e 100644
--- a/test/metabase/agent_api/api_test.clj
+++ b/test/metabase/agent_api/api_test.clj
@@ -1161,7 +1161,13 @@
(is (true? (t2/select-one-fn :archived :model/Card :id card-id)))
;; Mirrors the REST archive flow -- without :archived_directly the card would only show up
;; as inherited-from-trash and stay invisible in the Trash UI.
- (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/question/" 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-question-replace-query-test
(testing "Replacing the underlying query via :query (base64)"
@@ -1309,17 +1315,6 @@
(is (= dest-coll-id (t2/select-one-fn :collection_id :model/Dashboard :id dash-id)))
;; cards on the dashboard should follow
(is (= dest-coll-id (t2/select-one-fn :collection_id :model/Card :id card-id)))))
- (testing "Archiving a dashboard cascades to its cards"
- (mt/with-temp [:model/Dashboard {dash-id :id} {:name "Dash To Archive"}
- :model/Card {card-id :id} {:name "Cascading Card"
- :dataset_query (orders-count-query)
- :display :table
- :dashboard_id dash-id}]
- (let [resp (mt/user-http-request :rasta :put 200 (str "agent/v1/dashboard/" dash-id)
- {:archived true})]
- (is (true? (:archived resp))))
- (is (true? (t2/select-one-fn :archived :model/Dashboard :id dash-id)))
- (is (true? (t2/select-one-fn :archived :model/Card :id card-id)))))
(testing "Returns 404 when dashboard does not exist"
(mt/user-http-request :rasta :put 404 "agent/v1/dashboard/999999"
{:name "doesn't matter"}))
@@ -1341,6 +1336,25 @@
(mt/user-http-request :rasta :put 403 (str "agent/v1/dashboard/" dash-id)
{:collection_id locked-id})))))
+(deftest update-dashboard-archive-test
+ (testing "Archiving a dashboard cascades to its cards"
+ (mt/with-temp [:model/Dashboard {dash-id :id} {:name "Dash To Archive"}
+ :model/Card {card-id :id} {:name "Cascading Card"
+ :dataset_query (orders-count-query)
+ :display :table
+ :dashboard_id dash-id}]
+ (let [resp (mt/user-http-request :rasta :put 200 (str "agent/v1/dashboard/" dash-id)
+ {:archived true})]
+ (is (true? (:archived resp))))
+ (is (true? (t2/select-one-fn :archived :model/Dashboard :id dash-id)))
+ (is (true? (t2/select-one-fn :archived :model/Card :id card-id)))
+ (testing "archival is a soft delete: archived: false reverses it, cards included"
+ (let [resp (mt/user-http-request :rasta :put 200 (str "agent/v1/dashboard/" dash-id)
+ {:archived false})]
+ (is (false? (:archived resp))))
+ (is (false? (t2/select-one-fn :archived :model/Dashboard :id dash-id)))
+ (is (false? (t2/select-one-fn :archived :model/Card :id card-id)))))))
+
(deftest update-dashboard-dashcards-add-test
(testing "Add a card to the dashboard (autoplaced)"
(mt/with-temp [:model/Dashboard {dash-id :id} {:name "Phase B Add Target"}