The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
ENG-11089: Advertise every MCP v2 scope on first connect (#84066)
bryand8036287df00
diff --git a/src/metabase/mcp/README.md b/src/metabase/mcp/README.mdindex 0ac6881d64d..72c1ebe6f49 100644--- a/src/metabase/mcp/README.md+++ b/src/metabase/mcp/README.md@@ -65,15 +65,16 @@ Wildcard patterns (e.g. `agent:*`) match any scope with that prefix.These scopes gate the MCP surface only. No REST endpoint may declare one as its `:scope`, so a new token issued to anMCP client grants nothing on the REST API.-Clients start with a baseline. The protected-resource metadata's `scopes_supported` and the `scope` of the 401-challenge both list only `agent:content:read agent:query:run`: a fresh connection can read,-query, and chart. Writes (`agent:content:write`), raw SQL (`agent:sql:run`), and alerts and subscriptions-(`agent:delivery:write`) need a step-up. The surface still accepts every scope in the table, and the authorization-server metadata still advertises all of them.--`agent:query:run` is in the baseline so that charts never need a step-up. Claude Desktop retries a tool after a-step-up over a session that doesn't declare MCP Apps support, so a stepped-up `visualize_query` is refused and its-chart never embeds.+The protected-resource metadata's `scopes_supported` and the `scope` of the 401 challenge both list every scope in+the table, so a fresh connection asks for all of them. Some clients do not step up after a 403: a manual reconnect+from Claude's connector settings registers a new client and asks for exactly what these list. When they listed only+the baseline, that reconnect never offered writes, raw SQL, or delivery, and the user had no way to grant them+(ENG-11089). The authorization server metadata advertises all of them too.++The baseline (`agent:content:read agent:query:run`) is locked on the consent screen: when a client requests one of+these, the user cannot untick it. `agent:query:run` is in the baseline so that charts never need a step-up. Claude+Desktop retries a tool after a step-up over a session that doesn't declare MCP Apps support, so a stepped-up+`visualize_query` is refused and its chart never embeds.A tool call or data resource read the token lacks a scope for is refused with HTTP 403 and a`WWW-Authenticate: Bearer error="insufficient_scope"` challenge whose `scope` lists the v2 scopes the token alreadydiff --git a/src/metabase/mcp/core.clj b/src/metabase/mcp/core.cljindex d0fcb3f7217..9ccf20aa629 100644--- a/src/metabase/mcp/core.clj+++ b/src/metabase/mcp/core.clj@@ -103,6 +103,7 @@mcp.paths/v2-surface-scopes)(defn v2-baseline-scopes- "The subset of [[v2-scopes]] a client is told to request when it first connects."+ "The subset of [[v2-scopes]] that the consent page locks: when a client requests one of these, the user cannot+ untick it."[]mcp.paths/v2-baseline-scopes)diff --git a/src/metabase/mcp/paths.clj b/src/metabase/mcp/paths.cljindex f2528712b19..e49a0480a68 100644--- a/src/metabase/mcp/paths.clj+++ b/src/metabase/mcp/paths.clj@@ -61,10 +61,11 @@"agent:delivery:write"])(def v2-baseline-scopes- "The subset of [[v2-surface-scopes]], in its order, that an MCP client is told to request when it first connects:- reading and running queries."- ;; A client reaches the rest of the surface (writes, raw SQL, delivery) by stepping up on a 403 `insufficient_scope`.- ;; `agent:query:run` is here because charts must not need a step-up: Claude Desktop retries a tool after step-up- ;; over a session that declares no MCP Apps support, so a stepped-up `visualize_query` is refused and never embeds.+ "The subset of [[v2-surface-scopes]], in its order, that the consent page locks: when a client requests one of+ these, the user cannot untick it. Reading and running queries. Every other requested scope can be unticked."+ ;; A user who unticks the rest (writes, raw SQL, delivery) reaches it later by stepping up on a 403+ ;; `insufficient_scope`. `agent:query:run` is here because charts must not need a step-up: Claude Desktop retries a+ ;; tool after step-up over a session that declares no MCP Apps support, so a stepped-up `visualize_query` is refused+ ;; and never embeds.["agent:content:read""agent:query:run"])diff --git a/src/metabase/mcp/v2/api.clj b/src/metabase/mcp/v2/api.cljindex fcf7a8379ff..bac55d7aa35 100644--- a/src/metabase/mcp/v2/api.clj+++ b/src/metabase/mcp/v2/api.clj@@ -213,14 +213,14 @@(def ^:private default-ask-scopes"The `scope` of the 401 challenge, which an uninstructed client requests on first connect. Every scope here must beinside the OAuth server's default grant ceiling."- ;; Tools are listed whatever scopes the token holds. A call needing a scope the token lacks is answered with a 403- ;; `insufficient_scope` naming the union of held and required scopes, so a client steps up to the rest of the surface- ;; rather than being granted it up front. Each tool also declares its scope in `securitySchemes`, which is draft- ;; SEP-1488 (modelcontextprotocol issue 1488) and supported by ChatGPT; it is not in MCP 2025-03-26, the version this- ;; server reports, so other clients learn the missing scope from the 403. The surface still accepts all of- ;; [[metabase.mcp.paths/v2-surface-scopes]]. A scope outside the ceiling is answered "Invalid scope" for a client that- ;; follows the challenge.- mcp.paths/v2-baseline-scopes)+ ;; The whole surface, not the baseline (ENG-11089). A client whose step-up is lossy, such as a manual reconnect from+ ;; Claude's connector settings, registers a fresh client and asks for exactly this. When this was the baseline, that+ ;; reconnect never offered the write scopes, so the user had no way to grant them. The consent page starts every+ ;; requested scope ticked and lets the user untick any outside the baseline, so a narrower grant is still one+ ;; untick away. A call needing a scope the token lacks is still answered with a 403 `insufficient_scope`, for+ ;; clients that step up. A scope outside the ceiling is answered "Invalid scope" for a client that follows the+ ;; challenge.+ mcp.paths/v2-surface-scopes)(def ^{:arglists '([request respond raise])} handler"Ring async handler for the MCP endpoint."diff --git a/src/metabase/oauth_server/api/metadata.clj b/src/metabase/oauth_server/api/metadata.cljindex c39b0aa5128..4ce104c81b4 100644--- a/src/metabase/oauth_server/api/metadata.clj+++ b/src/metabase/oauth_server/api/metadata.clj@@ -50,7 +50,8 @@(defn- protected-resource-metadata"OAuth Protected Resource Metadata (RFC 9728) advertising `resource-path` as the protected resource, with the- baseline scopes for `resource-path` as `:scopes_supported`."+ scopes that [[metabase.oauth-server.core/mcp-resource-advertised-scopes]] returns for `resource-path` as+ `:scopes_supported`."[resource-path];; The scopes are derived from `resource-path` rather than passed in, so the resource and its advertised scopes;; cannot disagree.diff --git a/src/metabase/oauth_server/core.clj b/src/metabase/oauth_server/core.cljindex a983028bf1d..116689029eb 100644--- a/src/metabase/oauth_server/core.clj+++ b/src/metabase/oauth_server/core.clj@@ -57,7 +57,7 @@"The scopes the MCP resource at `path` accepts, which [[narrow-scope-to-resource]] trims a grant to. Every path in[[metabase.mcp.paths/endpoint-paths]] now reaches the same v2 surface, so they all accept the same set: the scopesthe v2 tool registry gates on plus the resource scopes its UI tools render through. What the resource *advertises*- is the narrower [[mcp-resource-advertised-scopes]].+ is [[mcp-resource-advertised-scopes]].This branched while v1 was still served. v1's tools gated on the per-entity agent-API scopes(`agent:question:create`, `agent:sql:execute`, …), so the aliases that reached v1 had to advertise those or@@ -69,11 +69,12 @@(vec (into (sorted-set) (mcp/v2-scopes))))(defn mcp-resource-advertised-scopes- "The RFC 9728 `scopes_supported` for the MCP resource at `path`: the baseline a client requests on first connect, a- subset of [[mcp-resource-scopes]]."- ;; Narrower than what the resource accepts: a client reaches the rest by a 403 `insufficient_scope` step-up.+ "The RFC 9728 `scopes_supported` for the MCP resource at `path`: every v2 scope, in surface order, which Claude Code+ and the Claude connectors request on first connect."+ ;; The whole surface, not the baseline (ENG-11089): a manual reconnect asks for exactly this, so a narrower list left+ ;; the write scopes unreachable for clients whose step-up is lossy.[_path]- (vec (mcp/v2-baseline-scopes)))+ (vec (mcp/v2-scopes)))(defn default-grant-scopes"The scope set a dynamically-registered client is registered with when it sends no `scope` of its own (RFC 7591 makesdiff --git a/test/metabase/mcp/v2/api_test.clj b/test/metabase/mcp/v2/api_test.cljindex 31415c570b0..2b94833cc19 100644--- a/test/metabase/mcp/v2/api_test.clj+++ b/test/metabase/mcp/v2/api_test.clj@@ -558,9 +558,8 @@(testing scope(is (contains? grantable scope)"a scope the v2 challenge asks for must be one the OAuth server will actually grant")))))- (testing "GHY-4543: the challenge asks for the baseline, a subset of what the surface accepts, in surface order"- (is (= ["agent:content:read" "agent:query:run"] @#'v2.api/default-ask-scopes))- (is (= @#'v2.api/default-ask-scopes (filterv (set @#'v2.api/default-ask-scopes) mcp.paths/v2-surface-scopes)))))+ (testing "ENG-11089: the challenge asks for everything the surface accepts, in surface order"+ (is (= mcp.paths/v2-surface-scopes @#'v2.api/default-ask-scopes))))(def ^:private mcp-app-ui-capabilities"The `initialize` capabilities an MCP Apps host advertises. Tools gated on `:mcp-app-ui` are hidden from — and@@ -778,17 +777,17 @@(is (= 401 (:status response)))(is (str/includes? (get-in response [:headers "WWW-Authenticate"] "")"/.well-known/oauth-protected-resource/api/metabase-mcp"))))- (testing "GHY-4543: the challenge asks for the baseline, not everything the surface accepts. ChatGPT takes its- login scope from this parameter; every tool is still listed, and a call needing more is answered with- a 403 `insufficient_scope` step-up. The baseline includes agent:query:run, so charts never step up."+ (testing "ENG-11089: the challenge asks for every v2 scope. ChatGPT takes its login scope from this parameter, and a+ client that reconnects by hand rather than stepping up never sees a scope this leaves out."(doseq [path ["metabase-mcp" "mcp"]](testing path(let [response (client/client-full-response :post 401 path{:request-options {:headers {}}}(jsonrpc-request "initialize"))](is (str/ends-with? (get-in response [:headers "WWW-Authenticate"] "")- ", scope=\"agent:content:read agent:query:run\""))))))- (testing "GHY-4543: an invalid bearer token's challenge asks for the same baseline"+ (str ", scope=\"agent:content:read agent:content:write agent:query:run agent:sql:run "+ "agent:delivery:write\"")))))))+ (testing "ENG-11089: an invalid bearer token's challenge asks for the same scopes"(doseq [path ["metabase-mcp" "mcp"]](testing path(let [response (client/client-full-response :post 401 path@@ -798,7 +797,8 @@(is (= (str "Bearer realm=\"mcp\", ""resource_metadata=\"http://localhost:3000/.well-known/oauth-protected-resource""/api/" path "\", "- "scope=\"agent:content:read agent:query:run\", "+ "scope=\"agent:content:read agent:content:write agent:query:run agent:sql:run "+ "agent:delivery:write\", ""error=\"invalid_token\"")(get-in response [:headers "WWW-Authenticate"])))))))(testing "auth-params are comma-delimited per RFC 7235, the form every spec and vendor example@@ -809,7 +809,8 @@(is (= (str "Bearer realm=\"mcp\", ""resource_metadata=\"http://localhost:3000/.well-known/oauth-protected-resource""/api/metabase-mcp\", "- "scope=\"agent:content:read agent:query:run\"")+ "scope=\"agent:content:read agent:content:write agent:query:run agent:sql:run "+ "agent:delivery:write\"")(get-in response [:headers "WWW-Authenticate"])))))));;; ------------------------------------------------ Auth methods --------------------------------------------------@@ -1152,7 +1153,7 @@"and nothing was created")))))))(deftest baseline-token-steps-up-from-a-write-tool-test- (testing "GHY-4543: a client that connected with only the advertised baseline is challenged, on a write, for the+ (testing "GHY-4543: a client holding only the always-granted baseline is challenged, on a write, for thebaseline plus the scope that write needs, so its step-up keeps what it already holds"(do-with-bearer-token!(set mcp.paths/v2-baseline-scopes)@@ -1258,8 +1259,8 @@"no transport-internal marker leaks into a batch element")))))))))))(deftest baseline-token-reads-the-fields-catalog-test- (testing "GHY-4543, GHY-4939: the advertised baseline carries agent:content:read, so a freshly connected client reads the- fields catalog without stepping up"+ (testing "GHY-4543, GHY-4939: the locked baseline carries agent:content:read, so a client that unticked everything+ else still reads the fields catalog without stepping up"(do-with-bearer-token!(set mcp.paths/v2-baseline-scopes)(fn [headers]diff --git a/test/metabase/oauth_server/api_test.clj b/test/metabase/oauth_server/api_test.cljindex 86cb8881eab..68d15ef0faa 100644--- a/test/metabase/oauth_server/api_test.clj+++ b/test/metabase/oauth_server/api_test.clj@@ -51,12 +51,13 @@:scopes_supported sequential?}response))))))))-(deftest protected-resource-metadata-advertises-the-baseline-test- (testing "GHY-4543: every protected-resource endpoint, including the bare one, advertises only the baseline. Claude- Code and the Claude connectors take their first-login scope from `scopes_supported` here; every tool is- still listed, and a call needing more is answered with a 403 `insufficient_scope` step-up. The baseline- must be accepted by the `:resource` the document names, or the first login is narrowed away; asserted- against that `:resource` rather than the URL requested, so the two cannot drift."+(deftest protected-resource-metadata-advertises-every-v2-scope-test+ (testing "ENG-11089: every protected-resource endpoint, including the bare one, advertises every v2 scope. Claude+ Code and the Claude connectors take their first-login scope from `scopes_supported` here, and a manual+ reconnect from the connector settings asks for exactly this list, so a scope left out is one that client+ can never be granted. Every advertised scope must be accepted by the `:resource` the document names, or+ the first login is narrowed away; asserted against that `:resource` rather than the URL requested, so the+ two cannot drift."(mt/with-temporary-setting-values [site-url "http://localhost:3000"](doseq [url [".well-known/oauth-protected-resource"".well-known/oauth-protected-resource/api/metabase-mcp"@@ -64,7 +65,8 @@(testing url(let [response (mt/user-http-request :crowberto :get 200 url)resource-path (str/replace (:resource response) "http://localhost:3000" "")]- (is (= #{"agent:content:read" "agent:query:run"}+ (is (= #{"agent:content:read" "agent:content:write" "agent:query:run"+ "agent:sql:run" "agent:delivery:write"}(set (:scopes_supported response))))(is (empty? (remove (set (oauth-server/mcp-resource-scopes resource-path))(:scopes_supported response))))))))))@@ -91,9 +93,10 @@:authorization_servers ["http://localhost:3000"]:bearer_methods_supported ["header"]}response))- (testing "the bare path is the one clients probe, so it advertises the same baseline as the canonical+ (testing "the bare path is the one clients probe, so it advertises the same scopes as the canonicalpath it names, and none of the retired per-entity agent-API scopes"- (is (= #{"agent:content:read" "agent:query:run"}+ (is (= #{"agent:content:read" "agent:content:write" "agent:query:run"+ "agent:sql:run" "agent:delivery:write"}(set (:scopes_supported response))))(is (not (contains? (set (:scopes_supported response)) "agent:question:create"))))))))diff --git a/test/metabase/oauth_server/core_test.clj b/test/metabase/oauth_server/core_test.cljindex 68d1a7e500f..6246607bc58 100644--- a/test/metabase/oauth_server/core_test.clj+++ b/test/metabase/oauth_server/core_test.clj@@ -49,12 +49,13 @@(testing "and the authorization-server metadata set"(is (empty? (remove ceiling (oauth-server/supported-scopes))))))))-(deftest v2-default-ask-is-the-baseline-and-is-requestable-test- (testing "GHY-4543: the v2 401 challenge asks an uninstructed client for the baseline only: reading and querying,- but not SQL, writes or delivery. Every tool is listed whatever the token holds, and a call needing more is- answered with a 403 `insufficient_scope` step-up, so asking for less degrades to a consent prompt rather- than a hidden tool."- (is (= #{"agent:content:read" "agent:query:run"} (set @#'v2.api/default-ask-scopes)))+(deftest v2-default-ask-is-the-whole-surface-and-is-requestable-test+ (testing "ENG-11089: the v2 401 challenge asks an uninstructed client for every v2 scope. A manual reconnect from+ Claude's connector settings asks for exactly this, so a baseline-only challenge left SQL, writes and+ delivery unreachable. The user can still untick each one outside the baseline on the consent page."+ (is (= #{"agent:content:read" "agent:content:write" "agent:query:run"+ "agent:sql:run" "agent:delivery:write"}+ (set @#'v2.api/default-ask-scopes)))(testing "the surface still accepts every scope asked for, or narrowing strips the ask at consent"(is (empty? (remove (set (oauth-server/mcp-resource-scopes (mcp/mcp-canonical-path)))@#'v2.api/default-ask-scopes))))@@ -73,7 +74,7 @@advertised twice.GHY-4543: the protected-resource metadata advertises `mcp-resource-advertised-scopes`, a vector copied- from the `v2-baseline-scopes` literal, so a scope repeated there is repeated on the wire. The accepted+ from the `v2-surface-scopes` literal, so a scope repeated there is repeated on the wire. The acceptedset, `mcp-resource-scopes`, is built through a `sorted-set` and cannot repeat by construction; it ischecked too, alongside the literals both are built from, where a duplicate would be silently swallowed."(let [duplicates (fn [scopes] (->> scopes frequencies (filter (fn [[_ n]] (> n 1))) (map key) sort vec))]@@ -197,8 +198,8 @@[mcp-uri]"agent:content:read agent:question:create agent:sql:execute agent:query:run"))](is (= #{"agent:content:read" "agent:query:run"} narrowed))))- (testing "GHY-4543: every v2 scope survives narrowing on every alias, although the resource metadata- advertises only the baseline — otherwise a step-up for a write scope is stripped at consent"+ (testing "GHY-4543: every v2 scope survives narrowing on every alias — otherwise a first connect or a+ step-up for a write scope is stripped at consent"(let [v2-scopes ["agent:content:read" "agent:content:write" "agent:query:run""agent:sql:run" "agent:delivery:write"]](doseq [path (mcp/mcp-endpoint-paths)]