Skip to content

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

Docs: backfill create_question + create_dashboard MCP tools (#74654)

bryan6ec2fb2b56dd
diff --git a/src/metabase/agent_api/reference.md b/src/metabase/agent_api/reference.md
index 07676796559..cfd8c3fe3fe 100644
--- a/src/metabase/agent_api/reference.md
+++ b/src/metabase/agent_api/reference.md
@@ -600,6 +600,80 @@ Row limits:
- Simple queries (no aggregation): 2000 rows max
- Aggregated queries: 10000 rows max
+### POST /v1/question
+
+Save a previously constructed query as a named question (card).
+
+Request:
+
+```json
+{
+ "name": "Q3 Revenue by Region",
+ "query": "eyJkYXRhYmFzZSI6MSwi...",
+ "display": "bar",
+ "description": "Sum of order totals grouped by region",
+ "collection_id": 7,
+ "visualization_settings": {}
+}
+```
+
+| Field | Required | Description |
+|------------------------|----------|----------------------------------------------------------------------------------------------|
+| name | yes | Question name |
+| query | yes | Base64-encoded query string returned by /v2/construct-query |
+| display | no | Visualization type (`table`, `bar`, `line`, `pie`, etc.). Defaults to `table`. |
+| description | no | Free-text description |
+| collection_id | no | Target collection. Omit / null to save at the user's personal-collection root. |
+| visualization_settings | no | Map of viz settings |
+
+Response:
+
+```json
+{
+ "id": 42,
+ "name": "Q3 Revenue by Region",
+ "display": "bar",
+ "collection_id": 7,
+ "description": "Sum of order totals grouped by region"
+}
+```
+
+### POST /v1/dashboard
+
+Create a new dashboard, optionally populated with existing saved questions.
+When `question_ids` is provided, cards are auto-placed on the grid based on
+their display type.
+
+Request:
+
+```json
+{
+ "name": "Q3 Revenue Overview",
+ "description": "Top-line Q3 metrics",
+ "collection_id": 7,
+ "question_ids": [42, 43, 44]
+}
+```
+
+| Field | Required | Description |
+|---------------|----------|----------------------------------------------------------------------------|
+| name | yes | Dashboard name |
+| description | no | Free-text description |
+| collection_id | no | Target collection. Omit / null to save at the user's personal-collection root. |
+| question_ids | no | Existing card IDs to add as dashcards. User must have read access to each. |
+
+Response:
+
+```json
+{
+ "id": 11,
+ "name": "Q3 Revenue Overview",
+ "collection_id": 7,
+ "description": "Top-line Q3 metrics",
+ "dashcard_ids": [101, 102, 103]
+}
+```
+
## Typical workflow
1. **Search** — POST /v1/search to find relevant tables or metrics
@@ -612,6 +686,8 @@ Row limits:
5. **Execute** — POST /v1/execute with the base64-encoded query, or use
POST /v2/query to construct and execute in one round-trip with pagination
6. **Iterate** — Adjust the program and repeat steps 4-5
+7. **Save (optional)** — POST /v1/question to persist the query as a card, and
+ POST /v1/dashboard to assemble saved cards into a dashboard
## Error handling
diff --git a/src/metabase/mcp/README.md b/src/metabase/mcp/README.md
index 1b282369073..19146037dee 100644
--- a/src/metabase/mcp/README.md
+++ b/src/metabase/mcp/README.md
@@ -57,6 +57,8 @@ Access tokens are scoped to limit what tools a client can use:
| `agent:query:construct` | `construct_query` |
| `agent:query` | `query` |
| `agent:query:execute` | `execute_query` |
+| `agent:question:create` | `create_question` |
+| `agent:dashboard:create`| `create_dashboard` |
Wildcard patterns (e.g. `agent:*`) match any scope with that prefix.
@@ -82,6 +84,8 @@ The MCP server exposes these tools, dynamically generated from the Agent API end
| `construct_query` | Construct a query against a table or metric. Accepts the user's original `prompt` when available. Returns an opaque `query_handle` for use with `execute_query` or `visualize_query`. |
| `execute_query` | Execute a previously constructed query and return results with column metadata. |
| `query` | Query a table or metric directly. Supports pagination via continuation tokens. |
+| `create_question` | Save a constructed query as a named question (card). Takes the base64 `query` from `construct_query`, plus optional `display`, `description`, `collection_id`, `visualization_settings`. |
+| `create_dashboard` | Create a dashboard, optionally populated with saved questions via `question_ids`. Cards are auto-positioned on the grid by display type. |
Query results are limited to 200 rows per request. When more rows are available, the response includes a
`continuation_token` that can be passed back to fetch the next page.