Skip to content

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

Add endpoint for native query construction in expected format (#76717)

lbrdnkfe2715ef6b96
diff --git a/.clj-kondo/config/modules/config.edn b/.clj-kondo/config/modules/config.edn
index 7e12acd0841..6bed3024718 100644
--- a/.clj-kondo/config/modules/config.edn
+++ b/.clj-kondo/config/modules/config.edn
@@ -180,6 +180,7 @@
:model/Collection
:model/Dashboard
:model/DashboardCard
+ :model/Database
:model/Table
:model/User}}
diff --git a/src/metabase/agent_api/api.clj b/src/metabase/agent_api/api.clj
index 3b4db193e55..f419c849ad8 100644
--- a/src/metabase/agent_api/api.clj
+++ b/src/metabase/agent_api/api.clj
@@ -306,6 +306,48 @@
(cond-> {:query (-> query json/encode u/encode-base64)}
prompt (assoc :prompt prompt))))
+;;; --------------------------------------------- Construct Native Query ---------------------------------------------
+
+(mr/def ::construct-native-query-request
+ "Request body for /v1/construct-native-query: a target database and a raw SQL string."
+ [:map {:closed true}
+ [:database_id {:tool/description "Numeric id of the database to run the SQL against."}
+ ms/PositiveInt]
+ [:sql {:tool/description "The raw SQL query text."}
+ ms/NonBlankString]])
+
+(api.macros/defendpoint :post "/v1/construct-native-query" :- ::construct-query-response
+ "Construct a native (raw SQL) query against a database.
+
+ Wraps `sql` into a serialized native query and returns it base64-encoded — the same
+ `{\"query\": <base64>}` shape as /v2/construct-query — so it can be saved as a question via
+ /v1/question (the MCP layer swaps the base64 for a `query_handle`).
+
+ This endpoint does NOT execute the SQL; to run native SQL ad hoc use /v1/execute-sql. The
+ MBQL execution endpoints (/v1/execute, /v2/query) reject native queries by design, so a
+ handle produced here is for saving, not for /v2/query execution."
+ {:scope metabot/agent-sql-construct
+ :tool {:name "construct_native_query"
+ :description (str "Construct a native (raw SQL) query for the given database. Returns "
+ "`{\"query_handle\": \"<uuid>\"}` to feed `create_question` and save it "
+ "as a question. Use this ONLY for native SQL — for MBQL use "
+ "`construct_query`. This does NOT run the SQL; to execute SQL ad hoc "
+ "use `execute_sql`. Saving the resulting question requires native-query "
+ "permission on the target database.")
+ :annotations {:read-only? true :idempotent? true}}}
+ [_route-params
+ _query-params
+ {:keys [database_id sql]} :- ::construct-native-query-request]
+ ;; Construction does not run the query, but require the caller to at least be able to see the
+ ;; target database so a bogus/inaccessible database_id fails here rather than at save time.
+ (api/read-check :model/Database database_id)
+ ;; Emit MBQL 5 (via `lib/native-query` + `prepare-for-serialization`, same as `construct_query`)
+ (let [mp (lib-be/application-database-metadata-provider database_id)]
+ {:query (-> (lib/native-query mp sql)
+ lib/prepare-for-serialization
+ json/encode
+ u/encode-base64)}))
+
;;; ------------------------------------------------- Combined Query -------------------------------------------------
(defn- generate-continuation-token
@@ -762,16 +804,20 @@
(api.macros/defendpoint :post "/v1/question" :- ::create-question-response
"Save a previously constructed query as a named question (card).
- 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.
+ The `query` parameter accepts a `query_handle` (UUID) returned by `construct_query` (MBQL) or
+ `construct_native_query` (native SQL), or a base64-encoded query string. MCP callers should
+ always use the handle.
Optionally specify display type, description, collection, and visualization settings.
If `collection_id` is omitted the question 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."
+ The response `collection_path` is the saved location.
+
+ Saving a native (raw SQL) query requires native-query permission on the target database."
{:scope metabot/agent-question-create
:tool {:name "create_question"
:description (str "Save a query as a named question in Metabase. "
- "Pass the `query_handle` returned by `construct_query`. "
+ "Pass the `query_handle` returned by `construct_query` (MBQL) or "
+ "`construct_native_query` (native SQL). "
"Optionally set display type (table, bar, line, pie, etc.), "
"description, and target collection. "
"If you omit collection_id it's saved to the user's personal collection; "
@@ -850,13 +896,15 @@
"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.
- Pass `query` (a query_handle from construct_query, or a base64 MBQL string) to replace the underlying query."
+ 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."
{:scope metabot/agent-question-update
: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 "
- "(a query_handle from construct_query).")}}
+ "(a query_handle from construct_query or construct_native_query).")}}
[{:keys [id]} :- [:map [:id ms/PositiveInt]]
_query-params
body :- ::update-question-request]
diff --git a/src/metabase/mcp/README.md b/src/metabase/mcp/README.md
index 4a6444a29ac..42b857474dc 100644
--- a/src/metabase/mcp/README.md
+++ b/src/metabase/mcp/README.md
@@ -59,6 +59,7 @@ 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: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") |
@@ -92,6 +93,7 @@ The MCP server exposes these tools, dynamically generated from the Agent API end
| Tool | Description |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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`. |
+| `construct_native_query` | Construct a native (raw SQL) query for a database. Returns an opaque `query_handle` to feed `create_question` and save it. Does not execute the SQL; native handles are rejected by `execute_query`/`query` (use `execute_sql` to run raw SQL). |
| `query` | Query a table or metric directly. Supports pagination via continuation tokens. |
| `execute_query` | Execute a previously constructed query and return results with column metadata. |
| `execute_sql` | Execute a raw SQL query against a database. Requires the user to have native-query permission on the target database. Can be disabled instance-wide via the `mcp-execute-sql-enabled` setting. |
@@ -100,8 +102,8 @@ The MCP server exposes these tools, dynamically generated from the Agent API end
| Tool | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `create_question` | Save a query as a named question (card). Accepts a `query_handle` from `construct_query`. |
-| `update_question` | Update a saved question. Patch semantics. Setting `collection_id` moves the card. Setting `archived` archives it. |
+| `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). |
| `update_dashboard` | Update a dashboard's metadata (name, description, collection, archived). |
| `create_collection` | Create a new collection. Optionally nested under a `parent_collection_id`. |
diff --git a/src/metabase/mcp/tools.clj b/src/metabase/mcp/tools.clj
index 1331d78a3b7..7e61432e03d 100644
--- a/src/metabase/mcp/tools.clj
+++ b/src/metabase/mcp/tools.clj
@@ -120,8 +120,11 @@
"execute_query" execute-query-mcp-input-malli})
(def ^:private mcp-output-overrides
- "tool-name → Malli schema. Replaces the manifest's derived `:outputSchema`."
- {"construct_query" construct-query-mcp-output-malli})
+ "tool-name → Malli schema. Replaces the manifest's derived `:outputSchema`.
+ Both construct tools emit `{:query_handle}` via the body transform (see
+ [[tools-storing-query-handle]]), so they share the same output schema."
+ {"construct_query" construct-query-mcp-output-malli
+ "construct_native_query" construct-query-mcp-output-malli})
(defn- override->input-json-schema [malli tool-name]
(tools-manifest/assert-optional-fields-nullable! malli tool-name)
@@ -301,7 +304,7 @@
(mr/validator construct-query-mcp-output-malli))
(defn- make-store-construct-query-result
- "Build a body-transform fn for construct_query.
+ "Build a body-transform fn for the construct tools (`construct_query`, `construct_native_query`).
The fn stores the base64 payload server-side under the calling user (with the current MCP session id
recorded for cleanup) and returns {:query_handle uuid} instead of {:query base64}, so the LLM carries
a short opaque UUID rather than the full base64 string.
@@ -329,6 +332,11 @@
(def ^:private tools-accepting-query-handle
#{"execute_query" "query" "create_question" "update_question"})
+;; 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.
+(def ^:private tools-storing-query-handle
+ #{"construct_query" "construct_native_query"})
+
;;; ------------------------------------------------- Tool Dispatch -------------------------------------------------
(defn- text-content
@@ -446,7 +454,7 @@
[resolved-path
remaining-args] (interpolate-path path arguments)
api-path (strip-api-prefix resolved-path)
- body-transform-fn (when (= tool-name "construct_query")
+ body-transform-fn (when (tools-storing-query-handle tool-name)
(make-store-construct-query-result
session-id api/*current-user-id*))]
(invoke-agent-api method api-path token-scopes remaining-args
diff --git a/src/metabase/metabot/core.clj b/src/metabase/metabot/core.clj
index 3dffd95f9ed..523d6eba7b6 100644
--- a/src/metabase/metabot/core.clj
+++ b/src/metabase/metabot/core.clj
@@ -22,6 +22,8 @@
agent-question-update
agent-resource-read
agent-search
+ agent-sql-construct
+ agent-sql-create
agent-sql-execute]
[metabase.metabot.search-models
entity-type->search-model
diff --git a/src/metabase/metabot/scope.clj b/src/metabase/metabot/scope.clj
index c20703a7d92..9a71f7b6521 100644
--- a/src/metabase/metabot/scope.clj
+++ b/src/metabase/metabot/scope.clj
@@ -17,6 +17,8 @@
;;; ──────────────────────────────────────────────────────────────────
;; SQL
+(api-scope/defscope agent-sql-construct "agent:sql:construct"
+ (deferred-tru "Construct SQL queries"))
(api-scope/defscope agent-sql-create "agent:sql:create"
(deferred-tru "Create SQL queries"))
(api-scope/defscope agent-sql-edit "agent:sql:edit"
diff --git a/test/metabase/agent_api/api_test.clj b/test/metabase/agent_api/api_test.clj
index 14238d31b40..ff09b8ad620 100644
--- a/test/metabase/agent_api/api_test.clj
+++ b/test/metabase/agent_api/api_test.clj
@@ -636,6 +636,51 @@
:query (:query construct-resp)
:collection_id locked-id}))))))
+;;; ----------------------------------------- Construct / Save Native Query ------------------------------------------
+
+(deftest construct-native-query-test
+ (testing "Wraps SQL into a base64-encoded MBQL 5 native query (same shape as /v2/construct-query output)"
+ (let [resp (mt/user-http-request :crowberto :post 200 "agent/v1/construct-native-query"
+ {:database_id (mt/id)
+ :sql "SELECT 1 AS n"})
+ decoded (-> resp :query u/decode-base64 json/decode+kw)]
+ (is (=? {:database (mt/id)
+ :lib/type "mbql/query"
+ :stages [{:lib/type "mbql.stage/native" :native "SELECT 1 AS n"}]}
+ decoded))))
+ (testing "Returns 403 when the caller cannot access the target database"
+ (mt/with-no-data-perms-for-all-users!
+ (mt/user-http-request :rasta :post 403 "agent/v1/construct-native-query"
+ {:database_id (mt/id)
+ :sql "SELECT 1"})))
+ (testing "Returns 404 for a non-existent database"
+ (mt/user-http-request :crowberto :post 404 "agent/v1/construct-native-query"
+ {:database_id Integer/MAX_VALUE
+ :sql "SELECT 1"})))
+
+(deftest create-native-question-test
+ (testing "Saves a native SQL query (from construct_native_query) as a question"
+ (let [construct-resp (mt/user-http-request :crowberto :post 200 "agent/v1/construct-native-query"
+ {:database_id (mt/id)
+ :sql "SELECT 1 AS n"})
+ create-resp (mt/user-http-request :crowberto :post 200 "agent/v1/question"
+ {:name "Native Agent Question"
+ :query (:query construct-resp)})]
+ (is (=? {:id pos? :name "Native Agent Question" :display "table"} create-resp))
+ (let [card (t2/select-one :model/Card :id (:id create-resp))]
+ (is (= :native (:query_type card)))
+ (is (=? {:stages [{:lib/type :mbql.stage/native :native "SELECT 1 AS n"}]}
+ (:dataset_query card))))
+ (t2/delete! :model/Card :id (:id create-resp))))
+ (testing "Returns 403 when the caller lacks native-query permission"
+ (let [construct-resp (mt/user-http-request :crowberto :post 200 "agent/v1/construct-native-query"
+ {:database_id (mt/id)
+ :sql "SELECT 1 AS n"})]
+ (mt/with-no-data-perms-for-all-users!
+ (mt/user-http-request :rasta :post 403 "agent/v1/question"
+ {:name "Should Not Save Native"
+ :query (:query construct-resp)})))))
+
(deftest create-question-explicit-null-collection-test
(testing "An explicit null collection_id saves to the root collection, not the personal default"
(let [construct-resp (mt/user-http-request :rasta :post 200 "agent/v2/construct-query"
diff --git a/test/metabase/mcp/api_test.clj b/test/metabase/mcp/api_test.clj
index 2ab14571033..f2320458439 100644
--- a/test/metabase/mcp/api_test.clj
+++ b/test/metabase/mcp/api_test.clj
@@ -271,6 +271,7 @@
(def ^:private all-tool-names
#{"construct_query"
+ "construct_native_query"
"create_collection"
"create_dashboard"
"create_question"
@@ -658,7 +659,7 @@
below) — the test compares this set against the Agent API-backed tools and
fails when they diverge, ensuring no Agent API tool ships without a basic
invocation check."
- #{"search" "construct_query" "query" "execute_query" "execute_sql"
+ #{"search" "construct_query" "construct_native_query" "query" "execute_query" "execute_sql"
"read_resource"
"create_question" "create_dashboard"
"update_question" "update_dashboard" "create_collection"})
@@ -694,6 +695,10 @@
_ (call-tool session-id "search" {:term_queries ["orders"]})
;; Query construction + execution
construct-data (call-tool session-id "construct_query" {:query orders-query})
+ native-data (call-tool session-id "construct_native_query"
+ {:database_id (mt/id)
+ :sql "SELECT 1"})
+ _ (is (uuid? (parse-uuid (:query_handle native-data))))
_ (call-tool session-id "query" {:query orders-query})
_ (call-tool session-id "execute_query"
{:query_handle (:query_handle construct-data)})