Skip to content

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

Fix issues with Codex MCP search + query pagination/row limit semantics (#72741)

Noah Moss892d4468ef8b
diff --git a/src/metabase/agent_api/api.clj b/src/metabase/agent_api/api.clj
index f57613ec13a..6f2a4eddae6 100644
--- a/src/metabase/agent_api/api.clj
+++ b/src/metabase/agent_api/api.clj
@@ -10,6 +10,7 @@
[metabase.api.macros.scope :as scope]
[metabase.api.routes.common :as api.routes.common]
[metabase.auth-identity.core :as auth-identity]
+ [metabase.lib.core :as lib]
[metabase.lib.schema.id :as lib.schema.id]
[metabase.metabot.core :as metabot]
[metabase.metabot.tools.construct :as metabot-construct]
@@ -35,14 +36,19 @@
30)
(def ^:private ^:const default-query-row-limit
- "Default row limit for table queries when no limit is specified."
+ "Default row cap when :limit is omitted from a table query request."
200)
-(def ^:private ^:const max-query-row-limit
- "Hard cap on rows returned by the combined query endpoint, keeping result sets lean for LLM context windows.
- Agents can paginate via continuation tokens for more."
+(def ^:private ^:const page-size
+ "Rows returned per page when paginating the combined query endpoint via continuation tokens.
+ Also used as the query processor's per-call row constraint."
200)
+(def ^:private ^:const max-total-row-limit
+ "Ceiling on the user-requested :limit for the combined query endpoint. Agents can paginate
+ through up to this many rows across pages."
+ 2000)
+
;;; ---------------------------------------------------- Helpers ------------------------------------------------------
(defn- check-tool-result
@@ -293,6 +299,25 @@
:field-id field-id
:limit (or (request/limit) default-field-values-limit)})))
+(defn- coerce-query-list
+ "Defensive coercion for `/v1/search`'s query arguments. Some MCP clients (notably
+ Codex) serialize array args through a string layer, so a caller that intended to
+ send `[\"orders\"]` may actually send `\"[\\\"orders\\\"]\"`. Accept either shape:
+ an array is returned as-is; a string that parses as a JSON array of non-blank
+ strings is unwrapped; any other string is treated as a single-element query."
+ [v]
+ (cond
+ (nil? v) nil
+ (sequential? v) v
+ (string? v) (or (try
+ (let [parsed (json/decode+kw v)]
+ (when (and (sequential? parsed)
+ (every? #(and (string? %) (not (str/blank? %))) parsed))
+ parsed))
+ (catch Exception _ nil))
+ [v])
+ :else v))
+
(api.macros/defendpoint :post "/v1/search" :- ::search-response
"Search for tables and metrics.
@@ -300,18 +325,24 @@
Reciprocal Rank Fusion when both query types are provided."
{:scope metabot/agent-search
:tool {:name "search"
- :description "Search for tables and metrics in Metabase. Use term_queries for keyword search or semantic_queries for natural language search."
+ :description (str "Search for tables and metrics in Metabase. "
+ "Use term_queries for keyword search or semantic_queries for natural language search. "
+ "Both arguments are arrays of strings, for example term_queries: [\"orders\", \"revenue\"].")
:annotations {:read-only? true}}}
[_route-params
_query-params
{term-queries :term_queries
semantic-queries :semantic_queries}
:- [:map
- [:term_queries {:optional true} [:maybe [:sequential ms/NonBlankString]]]
- [:semantic_queries {:optional true} [:maybe [:sequential ms/NonBlankString]]]]]
+ [:term_queries {:optional true
+ :tool/description "Keyword search queries as an array of strings, for example [\"orders\", \"revenue\"]."}
+ [:maybe [:or [:sequential ms/NonBlankString] ms/NonBlankString]]]
+ [:semantic_queries {:optional true
+ :tool/description "Natural-language search queries as an array of strings, for example [\"how much revenue did we make\"]."}
+ [:maybe [:or [:sequential ms/NonBlankString] ms/NonBlankString]]]]]
(let [results (metabot-search/search
- {:term-queries (or term-queries [])
- :semantic-queries (or semantic-queries [])
+ {:term-queries (or (coerce-query-list term-queries) [])
+ :semantic-queries (or (coerce-query-list semantic-queries) [])
:entity-types ["table" "metric"]
:limit (or (request/limit) 50)})]
{:data results
@@ -339,19 +370,23 @@
rejected here."
#{"table" "card" "dataset" "metric"})
-(defn- evaluate-program-for-execution
- "Resolve a program's source entity, evaluate the program via agent-lib, and return a
- plain MBQL 5 query map. The JSON round-trip strips lib metadata so the query can be
- serialized into a continuation token."
+(defn- evaluate-program-to-live-query
+ "Resolve a program's source entity, evaluate the program via agent-lib, and return
+ the live lib query (with lib metadata attached)."
[program]
(let [source-type (get-in program [:source :type])]
(api/check (contains? allowed-program-source-types source-type)
[400 (str "top-level program source must be one of: "
(str/join ", " (sort allowed-program-source-types)))]))
(let [source-entity (metabot-construct/program-source->source-entity (:source program))
- result (metabot-construct/execute-program source-entity nil program)
- pmbql (get-in result [:structured-output :query])]
- (json/decode+kw (json/encode pmbql))))
+ result (metabot-construct/execute-program source-entity nil program)]
+ (get-in result [:structured-output :query])))
+
+(defn- evaluate-program-for-execution
+ "Evaluate a program and return a plain MBQL 5 query map suitable for serialization
+ into a continuation token and execution by the QP."
+ [program]
+ (lib/prepare-for-serialization (evaluate-program-to-live-query program)))
(api.macros/defendpoint :post "/v2/construct-query" :- ::construct-query-response
"Construct an MBQL query from a structured agent-lib program.
@@ -379,28 +414,62 @@
;;; ------------------------------------------------- Combined Query -------------------------------------------------
(defn- generate-continuation-token
- "Build a base64-encoded continuation token containing the query and next-page pagination info."
- [query-map limit page]
+ "Build a base64-encoded continuation token carrying the query and next-page pagination info.
+ :limit is the user's total row cap across all pages, not the per-page size."
+ [query-map total-limit page]
(-> {:query query-map
- :pagination {:limit limit :page (inc page)}}
+ :pagination {:limit total-limit :page (inc page)}}
json/encode
u/encode-base64))
(defn- decode-continuation-token
- "Decode a base64-encoded continuation token into {:query ... :pagination ...}."
+ "Decode a base64-encoded continuation token into {:query ... :pagination ...}.
+ The token is client-supplied, so sanity-check the pagination ints to turn
+ garbage into a 400 rather than a downstream 500. This is robustness, not a
+ security boundary — a caller can always issue a fresh program to run any
+ query they want."
[token]
- (-> token u/decode-base64 json/decode+kw))
-
-(defn- query-page-size
- "Determine the per-page row limit for an evaluated MBQL 5 query, taking the
- user-supplied limit (from the last stage) when present and capping at the
- combined query endpoint's hard maximum."
- [query-map]
- (let [user-limit (-> query-map :stages last :limit)]
- (min (or user-limit default-query-row-limit) max-query-row-limit)))
+ (let [decoded (-> token u/decode-base64 json/decode+kw)
+ {:keys [limit page]} (:pagination decoded)]
+ (api/check (and (int? limit) (pos? limit))
+ [400 "Invalid continuation token: limit must be a positive integer"])
+ (api/check (and (int? page) (pos? page))
+ [400 "Invalid continuation token: page must be a positive integer"])
+ decoded))
+
+(defn- total-row-limit
+ "The user's requested :limit, defaulted when absent and capped at the combined
+ endpoint's hard maximum. This is the app-level total-row budget enforced across
+ paginated responses; each page's QP-level cap comes from `:page.items`, which
+ `remaining-page-rows` clamps to respect this total."
+ [live-query]
+ (min (or (lib/current-limit live-query) default-query-row-limit)
+ max-total-row-limit))
+
+(defn- rows-before-page
+ "Total rows consumed by the pages preceding `page`. Single source of truth for
+ the page-size * (page - 1) arithmetic used by both sizing and pagination-exit."
+ [page]
+ (* (dec page) page-size))
+
+(defn- remaining-page-rows
+ "Rows to request for this page, respecting the user's total cap.
+ Returns at most page-size, and never more than remaining rows under the cap."
+ [total-limit page]
+ (max 0 (min page-size (- total-limit (rows-before-page page)))))
+
+(defn- more-pages-available?
+ "True when this page was filled to its requested size *and* the total cap still
+ has room for more rows — i.e. we should emit a continuation token."
+ [page total-limit rows-returned items]
+ (and (= rows-returned items)
+ (< (rows-before-page (inc page)) total-limit)))
(defn- apply-page-to-query
- "Apply :page clause to the last stage of a MBQL 5 query map."
+ "Set `:page` on the last stage of a serialized MBQL 5 query map. Operates on the
+ plain-map form because the continuation-token path only has that shape available —
+ rehydrating to a live lib query here would require a metadata provider we don't
+ currently plumb through the token."
[query-map page items]
(let [stages (:stages query-map)
last-idx (dec (count stages))]
@@ -416,11 +485,12 @@
:context :agent})))
(defn- prepare-combined-query
- "Apply the tighter row cap used by the combined query endpoint."
+ "Apply the tighter row cap used by the combined query endpoint. Each page is bounded
+ by page-size; the user's total-limit is enforced separately via pagination."
[query]
(assoc (prepare-agent-query query)
- :constraints {:max-results max-query-row-limit
- :max-results-bare-rows max-query-row-limit}))
+ :constraints {:max-results page-size
+ :max-results-bare-rows page-size}))
(mr/def ::query-request
"Request body for /v2/query. Accepts either a structured program or a continuation_token."
@@ -429,6 +499,19 @@
[:continuation [:map [:continuation_token ms/NonBlankString]]]
[:program ::program-request]])
+(defn- initial-page-state
+ "Normalize the two /v2/query entry points into a single {:query :total-limit :page}
+ shape. A fresh program evaluates the user's program and computes a total-row budget
+ from its `:limit`; a continuation token carries that state from a prior response."
+ [body]
+ (if-let [token (:continuation_token body)]
+ (let [{:keys [query pagination]} (decode-continuation-token token)]
+ {:query query :total-limit (:limit pagination) :page (:page pagination)})
+ (let [live-query (evaluate-program-to-live-query body)]
+ {:query (lib/prepare-for-serialization live-query)
+ :total-limit (total-row-limit live-query)
+ :page 1})))
+
(api.macros/defendpoint :post "/v2/query"
:- (streaming-response/streaming-response-schema ::query-response)
"Execute a structured program and stream the results, with continuation-token pagination.
@@ -447,13 +530,9 @@
[_route-params
_query-params
body :- ::query-request]
- (let [{:keys [query limit page]}
- (if-let [token (:continuation_token body)]
- (let [{:keys [query pagination]} (decode-continuation-token token)]
- {:query query :limit (:limit pagination) :page (:page pagination)})
- (let [query (evaluate-program-for-execution body)]
- {:query query :limit (query-page-size query) :page 1}))
- mbql5-with-page (apply-page-to-query query page limit)]
+ (let [{:keys [query total-limit page]} (initial-page-state body)
+ items (remaining-page-rows total-limit page)
+ mbql5-with-page (apply-page-to-query query page items)]
(qp.streaming/streaming-response
[rff :api]
(qp/process-query
@@ -462,8 +541,8 @@
rff
(fn [result]
(assoc result :continuation_token
- (when (= (:row_count result) limit)
- (generate-continuation-token query limit page)))))))))
+ (when (more-pages-available? page total-limit (:row_count result) items)
+ (generate-continuation-token query total-limit page)))))))))
;;; ------------------------------------------------- Execute Query --------------------------------------------------
diff --git a/src/metabase/mcp/tools.clj b/src/metabase/mcp/tools.clj
index d0dcdf9f61e..f63243f2ee2 100644
--- a/src/metabase/mcp/tools.clj
+++ b/src/metabase/mcp/tools.clj
@@ -77,6 +77,38 @@
(build-tool-index (:tools (manifest)))
@tool-index-delay))
+(defn- format-validation-detail
+ "Flatten a defendpoint schema-error map — humanized by `malli.error`, whose leaves
+ are vectors of message strings and whose intermediate nodes may be nested maps —
+ into a compact `field: msg, msg; field: msg` rendering for MCP error text."
+ [errors-map]
+ (->> errors-map
+ (map (fn [[k v]]
+ (str (name k) ": "
+ (cond
+ (map? v) (format-validation-detail v)
+ (sequential? v) (str/join ", " v)
+ :else (str v)))))
+ (str/join "; ")))
+
+(defn- extract-error-message
+ "Pull the best human-readable string out of an agent-api error response. Agent-api
+ returns `:specific-errors`/`:errors` for schema-validation 400s (see
+ [[metabase.api.macros/decode-and-validate-params]]) and `:message`/`:error` for
+ other failures — surfacing the validation detail turns \"Invalid body\" into an
+ actionable message for MCP clients."
+ [response]
+ (let [{msg :message :keys [specific-errors errors error]} (:body response)
+ detail (cond
+ (seq specific-errors) (format-validation-detail specific-errors)
+ (seq errors) (format-validation-detail errors))]
+ (cond
+ (and msg detail) (str msg " (" detail ")")
+ detail detail
+ msg msg
+ error error
+ :else (str "Agent API error: " (:status response)))))
+
;;; ------------------------------------------------- Tool Dispatch -------------------------------------------------
(defn- text-content
@@ -121,7 +153,11 @@
(deliver result (if (instance? StreamingResponse resp-body)
(capture-streaming-response resp-body)
response)))
- (fn [error] (deliver result {:status 500 :body {:message (ex-message error)}}))))
+ (fn [error]
+ (let [{:keys [status-code] :as data} (ex-data error)]
+ (deliver result {:status (or status-code 500)
+ :body (merge (select-keys data [:errors :specific-errors])
+ {:message (or (ex-message error) "Internal error")})})))))
(defn- invoke-agent-api
"Invoke an Agent API endpoint with a synthetic Ring request.
@@ -143,9 +179,7 @@
(text-content (:body response))
:else
- (error-content (or (some-> response :body :message)
- (some-> response :body :error)
- (str "Agent API error: " (:status response))))))))
+ (error-content (extract-error-message response))))))
(defn- interpolate-path
"Replace `{param}` placeholders in `path` with values from `arguments`.
diff --git a/test/metabase/agent_api/api_test.clj b/test/metabase/agent_api/api_test.clj
index 6c4a6d95adf..497e9f9e749 100644
--- a/test/metabase/agent_api/api_test.clj
+++ b/test/metabase/agent_api/api_test.clj
@@ -6,6 +6,7 @@
[environ.core :as env]
[java-time.api :as t]
[medley.core :as m]
+ [metabase.agent-api.api :as agent-api.api]
[metabase.agent-api.settings :as agent-api.settings]
[metabase.lib.core :as lib]
[metabase.lib.metadata :as lib.metadata]
@@ -230,6 +231,22 @@
(mt/user-http-request :rasta :post 200 "agent/v1/search"
{:term_queries ["AgentSearchTestTable"]}))))))))
+(deftest coerce-query-list-test
+ (let [coerce #'agent-api.api/coerce-query-list]
+ (testing "arrays pass through unchanged"
+ (is (= ["orders" "revenue"] (coerce ["orders" "revenue"]))))
+ (testing "nil stays nil"
+ (is (nil? (coerce nil))))
+ (testing "a bare string becomes a single-element list"
+ (is (= ["orders"] (coerce "orders"))))
+ (testing "a JSON-stringified array of strings is unwrapped"
+ (is (= ["orders" "revenue"] (coerce "[\"orders\", \"revenue\"]"))))
+ (testing "JSON arrays with non-string elements are not unwrapped — they fall back to a literal single query so that downstream :sequential NonBlankString validation is never bypassed"
+ (is (= ["[1, 2]"] (coerce "[1, 2]")))
+ (is (= ["[\"\"]"] (coerce "[\"\"]"))))
+ (testing "non-JSON strings become a single-element list"
+ (is (= ["not json ["] (coerce "not json ["))))))
+
(defn- decode-query
"Decode a base64-encoded query response to a Clojure map, then normalize it so lib functions work."
[response]
@@ -376,7 +393,7 @@
(:measures table))))))))
(deftest combined-query-test
- (testing "Returns results for a table query"
+ (testing "Returns results for a table query that fits in a single page"
(let [table-id (mt/id :orders)
field-id (visible-field-id table-id "ID")
response (mt/user-http-request :rasta :post 202 "agent/v2/query"
@@ -385,27 +402,29 @@
["limit" 5]]})]
(is (=? {:status "completed"
:row_count 5
- :continuation_token string?
+ :continuation_token nil?
:data {:cols sequential?
:rows (fn [rows] (= 5 (count rows)))}}
response))))
- (testing "Continuation token returns next page of results"
- (let [table-id (mt/id :orders)
- field-id (visible-field-id table-id "ID")
- page1 (mt/user-http-request :rasta :post 202 "agent/v2/query"
- {:source {:type "table" :id table-id}
- :operations [["order-by" ["field" field-id]]
- ["limit" 5]]})
- page2 (mt/user-http-request :rasta :post 202 "agent/v2/query"
- {:continuation_token (:continuation_token page1)})]
- (is (=? {:row_count 5
+ (testing "Continuation token returns next page of results when the total limit exceeds the page size"
+ (let [table-id (mt/id :orders)
+ field-id (visible-field-id table-id "ID")
+ page-size 200
+ total-rows 250
+ page1 (mt/user-http-request :rasta :post 202 "agent/v2/query"
+ {:source {:type "table" :id table-id}
+ :operations [["order-by" ["field" field-id]]
+ ["limit" total-rows]]})
+ page2 (mt/user-http-request :rasta :post 202 "agent/v2/query"
+ {:continuation_token (:continuation_token page1)})]
+ (is (=? {:row_count page-size
:continuation_token string?
- :data {:rows (fn [rows] (= 5 (count rows)))}}
+ :data {:rows (fn [rows] (= page-size (count rows)))}}
page1))
- (is (=? {:row_count 5
- :continuation_token string?
- :data {:rows (fn [rows] (= 5 (count rows)))}}
+ (is (=? {:row_count (- total-rows page-size)
+ :continuation_token nil?
+ :data {:rows (fn [rows] (= (- total-rows page-size) (count rows)))}}
page2))
(is (not= (get-in page1 [:data :rows])
(get-in page2 [:data :rows]))
@@ -418,13 +437,33 @@
{:source {:type "table" :id (mt/id :orders)}
:operations [["aggregate" ["count"]]]}))))
- (testing "Constraint cap limits results to 200 rows"
+ (testing "Per-page cap limits a single page to 200 rows even when the total limit is higher"
(is (=? {:status "completed"
:row_count (fn [n] (<= n 200))}
(mt/user-http-request :rasta :post 202 "agent/v2/query"
{:source {:type "table" :id (mt/id :orders)}
:operations [["limit" 1000]]})))))
+(defn- make-continuation-token [pagination]
+ (-> {:query {:database (mt/id) :stages [{:source-table (mt/id :orders)}]}
+ :pagination pagination}
+ json/encode
+ u/encode-base64))
+
+(deftest continuation-token-validation-test
+ (testing "Malformed pagination ints in a continuation token produce a 400, not a 500.
+ This is robustness — the token isn't a trust boundary, since a caller can
+ always issue a fresh program."
+ (doseq [[label pagination] [["zero limit" {:limit 0 :page 1}]
+ ["negative limit" {:limit -10 :page 1}]
+ ["non-integer limit" {:limit "lots" :page 1}]
+ ["zero page" {:limit 200 :page 0}]
+ ["negative page" {:limit 200 :page -1}]
+ ["non-integer page" {:limit 200 :page "next"}]]]
+ (testing label
+ (mt/user-http-request :rasta :post 400 "agent/v2/query"
+ {:continuation_token (make-continuation-token pagination)})))))
+
(deftest combined-query-metric-test
(mt/with-temp [:model/Card metric {:name "Test Metric"
:type :metric
diff --git a/test/metabase/mcp/api_test.clj b/test/metabase/mcp/api_test.clj
index 6cc8452cc54..f30c5f94879 100644
--- a/test/metabase/mcp/api_test.clj
+++ b/test/metabase/mcp/api_test.clj
@@ -181,7 +181,27 @@
(testing "each tool has a description and inputSchema"
(doseq [tool tools]
(is (string? (:description tool)))
- (is (map? (:inputSchema tool))))))))
+ (is (map? (:inputSchema tool)))))
+ (testing "search description guides clients toward the expected array shape"
+ (let [tools-by-name (into {} (map (juxt :name identity)) tools)
+ search-tool (get tools-by-name "search")
+ property-schema (fn [tool-name property-name]
+ (or (get-in tools-by-name [tool-name :inputSchema :properties property-name])
+ (get-in tools-by-name [tool-name :inputSchema :properties (keyword property-name)])))
+ collect-leaves (fn collect-leaves [schema]
+ (cond
+ (nil? schema) []
+ (:oneOf schema) (mapcat collect-leaves (:oneOf schema))
+ (:anyOf schema) (mapcat collect-leaves (:anyOf schema))
+ :else [schema]))
+ leaf-types (fn [schema] (set (keep :type (collect-leaves schema))))
+ array-branch (fn [schema]
+ (some #(when (= "array" (:type %)) %) (collect-leaves schema)))]
+ (is (str/includes? (:description search-tool) "arrays of strings"))
+ (is (contains? (leaf-types (property-schema "search" "term_queries")) "array"))
+ (is (= "string" (get-in (array-branch (property-schema "search" "term_queries")) [:items :type])))
+ (is (contains? (leaf-types (property-schema "search" "semantic_queries")) "array"))
+ (is (= "string" (get-in (array-branch (property-schema "search" "semantic_queries")) [:items :type]))))))))
(deftest ping-test
(testing "ping returns empty result"
@@ -234,6 +254,33 @@
(is (= 200 (:status response)))
(is (nil? (:isError result)))
(is (= "text" (:type (first (:content result)))))
+ (let [search-data (json/decode+kw (:text (first (:content result))))]
+ (is (contains? search-data :data))
+ (is (contains? search-data :total_count))))))
+
+ (testing "search accepts a singleton string as a one-element query list"
+ (search.tu/with-legacy-search
+ (let [[session-id _] (initialize!)
+ response (mcp-request (jsonrpc-request "tools/call"
+ {:name "search"
+ :arguments {:term_queries "orders"}})
+ {"mcp-session-id" session-id})
+ result (get-in response [:body :result])]
+ (is (= 200 (:status response)))
+ (is (nil? (:isError result)))
+ (let [search-data (json/decode+kw (:text (first (:content result))))]
+ (is (contains? search-data :data))))))
+
+ (testing "search coerces JSON-stringified arrays so clients that serialize args through a string layer still work"
+ (search.tu/with-legacy-search
+ (let [[session-id _] (initialize!)
+ response (mcp-request (jsonrpc-request "tools/call"
+ {:name "search"
+ :arguments {:term_queries "[\"orders\"]"}})
+ {"mcp-session-id" session-id})
+ result (get-in response [:body :result])]
+ (is (= 200 (:status response)))
+ (is (nil? (:isError result)))
(let [search-data (json/decode+kw (:text (first (:content result))))]
(is (contains? search-data :data))
(is (contains? search-data :total_count)))))))