### Summary Follow-up to !260668, agreed in review there. The two MCP endpoints, `/api/v4/mcp` and `/api/v4/orbit/mcp`, answer a request with no token, or with a token GitLab does not know, with a `401` whose challenge [`API::Helpers::Mcp::AuthChallenge`](https://gitlab.com/gitlab-org/gitlab/-/blob/c567a00380fcf816ffa897a706f2b820a3aa475b/lib/api/helpers/mcp/auth_challenge.rb#L13-34) builds: `realm="GitLab"`, the endpoint's own scope from [`Gitlab::Auth::MCP_RESOURCE_SCOPES`](https://gitlab.com/gitlab-org/gitlab/-/blob/c567a00380fcf816ffa897a706f2b820a3aa475b/lib/gitlab/auth.rb#L33-36) (`mcp` or `mcp_orbit`), and `resource_metadata`. The other refusals of a token on these endpoints are built elsewhere and say something different: 1. **The `insufficient_scope` 403** comes from the shared API guard ([`lib/api/api_guard.rb:217-223`](https://gitlab.com/gitlab-org/gitlab/-/blob/c567a00380fcf816ffa897a706f2b820a3aa475b/lib/api/api_guard.rb#L217-223)). On `master` it carries no `WWW-Authenticate` header (the `FIXME` there). !260668 adds the guard's challenge, which has the guard's realm, no `resource_metadata`, and in `scope` the scopes the guard's check accepts for the request rather than the endpoint's scope: `mcp api` for a `POST` to `/api/v4/mcp`. 1. **On `/api/v4/mcp`, a token that has `api` and not `mcp` gets a plain 403.** `API::API` registers `api` with no condition ([`lib/api/api.rb:58`](https://gitlab.com/gitlab-org/gitlab/-/blob/c567a00380fcf816ffa897a706f2b820a3aa475b/lib/api/api.rb#L58)), so the guard's check accepts the token, and the endpoint's own check refuses it afterwards with `forbidden!` ([`lib/api/mcp/base.rb:68-69`](https://gitlab.com/gitlab-org/gitlab/-/blob/c567a00380fcf816ffa897a706f2b820a3aa475b/lib/api/mcp/base.rb#L68-69)): `{"message":"403 Forbidden"}` and no challenge, on `master` and with !260668 alike. So `api`, which the 403 above names, is a scope this endpoint refuses, and the refusal gives a client nothing to step up from. 1. **An expired or revoked token, or an impersonation token while impersonation is disabled, gets the guard's `invalid_token` 401** ([`lib/api/api_guard.rb:202-215`](https://gitlab.com/gitlab-org/gitlab/-/blob/c567a00380fcf816ffa897a706f2b820a3aa475b/lib/api/api_guard.rb#L202-215)), with the guard's realm and no `resource_metadata` or `scope`. #604654 asked for `resource_metadata` there and was closed after !243210 and !243212. Those add the challenge in `unauthorized!`, which answers a request with no token or an unknown one; none of these tokens reaches it. The MCP authorization specification asks for `error="insufficient_scope"`, the scopes needed and `resource_metadata` on that 403, "for consistency with 401 responses" ([2025-11-25, Runtime Insufficient Scope Errors](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#runtime-insufficient-scope-errors)), and its step-up flow has the client read that challenge and request the scopes it names. ### Steps to reproduce 1. On an instance with [access to the MCP server](https://docs.gitlab.com/administration/settings/visibility_and_access_controls/#allow-access-to-the-mcp-server) turned on, create personal access tokens with only `read_user` and with only `api`, and a third that you then revoke. 1. Send an MCP `initialize` request to `/api/v4/mcp` with each of them, and with none: ```shell curl --include --request POST --header "Authorization: Bearer <token>" \ --header "Content-Type: application/json" \ --data '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2025-06-18"}}' \ "https://gitlab.example.com/api/v4/mcp" ``` 1. Send the same requests to `/api/v4/orbit/mcp`, except the `api` one, which that endpoint accepts. ### Example Project Not needed: the responses do not depend on any project. ### What is the current *bug* behavior? On `/api/v4/mcp`, with !260668 applied: | Request | Status | `WWW-Authenticate` | | ------ | ------ | ------ | | No token, or an unknown one | `401` | `Bearer realm="GitLab", scope="mcp", resource_metadata="<url>/.well-known/oauth-protected-resource/api/v4/mcp"` | | Expired or revoked token, or an impersonation token while impersonation is disabled | `401` | `Bearer realm="Protected by OAuth 2.0", error="invalid_token", error_description="Token is expired. You can either do re-authorization or token refresh."` (or `"Token was revoked. ..."`, `"Token is an impersonation token but impersonation was disabled."`) | | Token with only `read_user` | `403` | `Bearer realm="Protected by OAuth 2.0", error="insufficient_scope", error_description="The request requires higher privileges than provided by the access token.", scope="mcp api"`, and none on `master` | | Token with `api` and not `mcp` | `403` | none, and the body is `{"message":"403 Forbidden"}` | `/api/v4/orbit/mcp` answers the first three rows the same, with `mcp_orbit` and its own metadata URL in the first and `scope="mcp_orbit mcp read_api ai_workflows api"` in the third, and it accepts a token with `api`. Every scope in that list is one the Orbit endpoint accepts. ### What is the expected *correct* behavior? On both endpoints, the `insufficient_scope` 403 and the `invalid_token` 401 carry the parameters of the challenge the 401 already carries, with `error` and `error_description` added, and the body's `scope` matches the header's: ```plaintext WWW-Authenticate: Bearer realm="GitLab", error="insufficient_scope", error_description="The request requires higher privileges than provided by the access token.", scope="mcp", resource_metadata="https://gitlab.example.com/.well-known/oauth-protected-resource/api/v4/mcp" ``` On `/api/v4/mcp` the scope is `mcp`: it is what the 401 there already names, and the scope GitLab sets on an authorization request for that resource and for a dynamically registered client limited to `mcp` ([`Oauth::AuthorizationsController#pre_auth_params`](https://gitlab.com/gitlab-org/gitlab/-/blob/c567a00380fcf816ffa897a706f2b820a3aa475b/app/controllers/oauth/authorizations_controller.rb#L147-155)). A token that passes the guard only through `api` gets this 403 instead of the plain one. On `/api/v4/orbit/mcp`, the 401 names `mcp_orbit`, which the same method sets for that resource and for a dynamically registered client limited to `mcp_orbit`. Whether its 403 names only that scope or keeps the list of every scope the endpoint accepts is open, since all of them work there. The `insufficient_granular_scope` 403 that fine-grained tokens get is out of scope here. ### Relevant logs and/or screenshots <details><summary>Responses from a throwaway request spec on !260668's branch</summary> ```plaintext POST /api/v4/mcp, no token 401 WWW-Authenticate: Bearer realm="GitLab", scope="mcp", resource_metadata="http://localhost/.well-known/oauth-protected-resource/api/v4/mcp" {"message":"401 Unauthorized"} POST /api/v4/mcp, unknown personal access token 401 WWW-Authenticate: Bearer realm="GitLab", scope="mcp", resource_metadata="http://localhost/.well-known/oauth-protected-resource/api/v4/mcp" {"message":"401 Unauthorized"} POST /api/v4/mcp, expired OAuth token 401 WWW-Authenticate: Bearer realm="Protected by OAuth 2.0", error="invalid_token", error_description="Token is expired. You can either do re-authorization or token refresh." {"error":"invalid_token","error_description":"Token is expired. You can either do re-authorization or token refresh."} POST /api/v4/mcp, revoked personal access token 401 WWW-Authenticate: Bearer realm="Protected by OAuth 2.0", error="invalid_token", error_description="Token was revoked. You have to re-authorize from the user." {"error":"invalid_token","error_description":"Token was revoked. You have to re-authorize from the user."} POST /api/v4/mcp, impersonation token with mcp, impersonation disabled 401 WWW-Authenticate: Bearer realm="Protected by OAuth 2.0", error="invalid_token", error_description="Token is an impersonation token but impersonation was disabled." {"error":"invalid_token","error_description":"Token is an impersonation token but impersonation was disabled."} POST /api/v4/mcp, OAuth token with read_user 403 WWW-Authenticate: Bearer realm="Protected by OAuth 2.0", error="insufficient_scope", error_description="The request requires higher privileges than provided by the access token.", scope="mcp api" {"error":"insufficient_scope","error_description":"The request requires higher privileges than provided by the access token.","scope":"mcp api"} POST /api/v4/mcp, personal access token with api 403 (no WWW-Authenticate) {"message":"403 Forbidden"} POST /api/v4/orbit/mcp, no token 401 WWW-Authenticate: Bearer realm="GitLab", scope="mcp_orbit", resource_metadata="http://localhost/.well-known/oauth-protected-resource/api/v4/orbit/mcp" {"message":"401 Unauthorized"} POST /api/v4/orbit/mcp, expired OAuth token 401 WWW-Authenticate: Bearer realm="Protected by OAuth 2.0", error="invalid_token", error_description="Token is expired. You can either do re-authorization or token refresh." {"error":"invalid_token","error_description":"Token is expired. You can either do re-authorization or token refresh."} POST /api/v4/orbit/mcp, OAuth token with read_user 403 WWW-Authenticate: Bearer realm="Protected by OAuth 2.0", error="insufficient_scope", error_description="The request requires higher privileges than provided by the access token.", scope="mcp_orbit mcp read_api ai_workflows api" {"error":"insufficient_scope","error_description":"The request requires higher privileges than provided by the access token.","scope":"mcp_orbit mcp read_api ai_workflows api"} ``` An OAuth token and a personal access token with the same scopes, or in the same state, got the same answer in every case. </details> ### Output of checks #### Results of GitLab environment info The code is cited from `master` at `c567a00380f`. The responses above come from a throwaway request spec on !260668's branch at `197a5063` (`master` at `cc09e01a` plus that MR), where the guard's handling of expired, revoked and impersonation tokens, `AuthChallenge` and both endpoints' `before` blocks are the same as on `master`. ### Possible fixes - Build every challenge on these endpoints in `AuthChallenge`, taking `error` and `error_description` as well, and have the guard's error handler use it when the endpoint includes `AuthChallenge`. The handler runs in the endpoint's context, so `request` and the resource path are there. The body's `scope` should come from the same value, so the two keep agreeing as they do after !260668. - On `/api/v4/mcp`, raise `Gitlab::Auth::InsufficientScopeError` with `[Gitlab::Auth::MCP_SCOPE]` instead of calling `forbidden!` at `lib/api/mcp/base.rb:68-69`, so the token with only `api` gets the same answer from the same handler.