Skip to content

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

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.md
index 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 an
MCP 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 already
diff --git a/src/metabase/mcp/core.clj b/src/metabase/mcp/core.clj
index 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.clj
index 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.clj
index 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 be
inside 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.clj
index 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.clj
index 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 scopes
the 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 makes
diff --git a/test/metabase/mcp/v2/api_test.clj b/test/metabase/mcp/v2/api_test.clj
index 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 the
baseline 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.clj
index 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 canonical
path 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.clj
index 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 accepted
set, `mcp-resource-scopes`, is built through a `sorted-set` and cannot repeat by construction; it is
checked 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)]