Docs: GitLab MCP Server oauth error with mcp-remote 0.1.27+ (wrong scope passed by client library)
Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.
Summary
Configuring an MCP client in IDEs (Cursor, etc.) and CLIs causes an oauth callback error with GitLab.com and blocks from further use of the GitLab MCP Server.
The problem started with the mcp-remote NodeJS module in version 0.1.27+.
Reported in #561564 (comment 2720560430) and workaround docs issue in #566925 (closed) cc @fsieverding @tkomatsubara @iganbaruch @mwoolf @jglassman1
Workarounds
- Add the static oauth metadata flag proposed in #566965 (comment 2721850726) -- please report in that thread when it works, so we can document it.
- Pin to 0.1.26 version
"mcp-remote@0.1.26"(not recommended for security reasons)
Helpful context why the scope is enforced
This was a conscious design decision at the time. Our implementation of OAuth dynamic application registration forces scope to
mcp, regardless of input since the only use-case we wanted to support at this time was an MCP server. This is a self-imposed restriction, and not one specified either by the MCP specification, or an OAuth one. It could be changed but this allows us to restrict the use of MCP tools only to supported API endpoints.
Steps to reproduce
- Open Cursor or equivalent IDE that supports MCP
- Right top corner gear - Settings - Tools & Integrations
Add Custom MCP- Fill in the following JSON
{
"mcpServers": {
"GitLab": {
"command": "npx",
"args": [
"-y",
"mcp-remote@latest",
"https://gitlab.com/api/v4/mcp"
]
}
}
}Example Project
Any project will work but I used https://gitlab.com/gitlab-da/use-cases/ai/gitlab-duo-agent-platform/challenges/challenge-cpp-observability-sensor
What is the current bug behavior?
After the MCP client creates the authentication callback with the oauth URL, the GitLab server oauth response is broken, saying
An error has occurred
The requested scope is invalid, unknown, or malformed.
and you cannot authenticate against the GitLab MCP Server.
What is the expected correct behavior?
MCP configuration and oauth works with the callback URL, and offers to authorize the application.
Relevant logs and/or screenshots
2025-09-01 11:47:07.744 [info] Handling ListOfferings action, server stored: false
2025-09-01 11:47:07.744 [error] No server info found
2025-09-01 11:47:07.744 [info] Handling CreateClient action
2025-09-01 11:47:07.744 [info] Starting new stdio process with command: npx -y mcp-remote@latest https://gitlab.com/api/v4/mcp
2025-09-01 11:47:11.522 [error] [33292] Using automatically selected callback port: 12849
2025-09-01 11:47:11.523 [error] [33292] [33292] Connecting to remote server: https://gitlab.com/api/v4/mcp
[33292] Using transport strategy: http-first
2025-09-01 11:47:12.988 [error] [33292]
Please authorize this client by visiting:
https://gitlab.com/oauth/authorize?response_type=code&client_id=REPLACED&code_challenge=REPLACED&code_challenge_method=S256&redirect_uri=http%3A%2F%2Flocalhost%3A12849%2Foauth%2Fcallback&state=REPLACED
2025-09-01 11:47:12.994 [error] [33292] Browser opened automatically.
2025-09-01 11:47:12.994 [error] [33292] Authentication required. Initializing auth...
2025-09-01 11:47:12.995 [error] [33292] Initializing auth coordination on-demand
2025-09-01 11:47:12.996 [error] [33292] Creating lockfile for server 252ab552f8636c5b82dfd2622f4486b1 with process 33292 on port 12849
2025-09-01 11:47:12.996 [error] [33292] OAuth callback server running at http://127.0.0.1:12849
2025-09-01 11:47:12.998 [error] [33292] Authentication required. Waiting for authorization...
https://gitlab.com/oauth/authorize?response_type=code&client_id=REPLACED&code_challenge=REPLACED&code_challenge_method=S256&redirect_uri=http%3A%2F%2Flocalhost%3A12849%2Foauth%2Fcallback&state=REPLACEDCompared to 0.1.26 working
2025-09-01 11:50:34.754 [info] Handling CreateClient action
2025-09-01 11:50:34.754 [info] Starting new stdio process with command: npx -y mcp-remote@0.1.26 https://gitlab.com/api/v4/mcp
2025-09-01 11:50:34.758 [info] Handling DeleteClient action
2025-09-01 11:50:34.760 [info] Handling CreateClient action
2025-09-01 11:50:34.761 [info] Starting new stdio process with command: npx -y mcp-remote@0.1.26 https://gitlab.com/api/v4/mcp
2025-09-01 11:50:36.830 [error] [36879] Using automatically selected callback port: 12849
2025-09-01 11:50:36.831 [error] [36879] [36879] Connecting to remote server: https://gitlab.com/api/v4/mcp
[36879] Using transport strategy: http-first
2025-09-01 11:50:37.062 [error] [36910] Using automatically selected callback port: 12849
2025-09-01 11:50:37.063 [error] [36910] [36910] Connecting to remote server: https://gitlab.com/api/v4/mcp
2025-09-01 11:50:37.063 [error] [36910] Using transport strategy: http-first
2025-09-01 11:50:38.318 [error] [36910]
Please authorize this client by visiting:
https://gitlab.com/oauth/authorize?response_type=code&client_id=REPLACED&code_challenge=REPLACED&code_challenge_method=S256&redirect_uri=http%3A%2F%2Flocalhost%3A12849%2Foauth%2Fcallback&state=REPLACED&scope=mcp
2025-09-01 11:50:38.322 [error] [36910] Browser opened automatically.
2025-09-01 11:50:38.323 [error] [36879]
Please authorize this client by visiting:
https://gitlab.com/oauth/authorize?response_type=code&client_id=REPLACED&code_challenge=REPLACED&code_challenge_method=S256&redirect_uri=http%3A%2F%2Flocalhost%3A12849%2Foauth%2Fcallback&state=REPLACED
2025-09-01 11:50:38.323 [error] [36910] Authentication required. Initializing auth...
2025-09-01 11:50:38.323 [error] [36910] Initializing auth coordination on-demand
2025-09-01 11:50:38.325 [error] [36910] Creating lockfile for server 252ab552f8636c5b82dfd2622f4486b1 with process 36910 on port 12849
2025-09-01 11:50:38.326 [error] [36910] OAuth callback server running at http://127.0.0.1:12849
2025-09-01 11:50:38.326 [error] [36910] Authentication required. Waiting for authorization...
2025-09-01 11:50:38.328 [error] [36879] Browser opened automatically.
2025-09-01 11:50:38.329 [error] [36879] Authentication required. Initializing auth...
2025-09-01 11:50:38.329 [error] [36879] Initializing auth coordination on-demand
2025-09-01 11:50:38.333 [error] [36910] Client requested no long poll, responding with 202
2025-09-01 11:50:38.336 [error] [36879] Another instance is handling authentication on port 12849 (pid: 36910)
2025-09-01 11:50:38.336 [error] [36879] Waiting for authentication from the server on port 12849...
[36879] Querying: http://127.0.0.1:12849/wait-for-auth
2025-09-01 11:51:08.341 [error] [36910] Long poll timeout reached, responding with 202
2025-09-01 11:51:08.345 [error] [36879] Authentication still in progress
2025-09-01 11:51:09.347 [error] [36879] Querying: http://127.0.0.1:12849/wait-for-auth
2025-09-01 11:51:34.758 [info] Client closed for command
2025-09-01 11:51:34.761 [info] Handling ListOfferings action, server stored: false
2025-09-01 11:51:34.761 [error] No server info found
2025-09-01 11:51:34.762 [info] Client closed for command
2025-09-01 11:51:34.762 [info] Handling ListOfferings action, server stored: false
2025-09-01 11:51:34.762 [error] No server info found
2025-09-01 11:51:34.766 [info] Handling ListOfferings action, server stored: false
2025-09-01 11:51:34.766 [error] No server info found
2025-09-01 11:51:34.766 [info] Handling ListOfferings action, server stored: false
2025-09-01 11:51:34.766 [error] No server info found
2025-09-01 11:51:34.769 [info] Client closed for command
2025-09-01 11:51:34.769 [info] Client closed for commandOutput of checks
Reproduced on GitLab.com
Results of GitLab environment info
Expand for output related to GitLab environment info
(For installations with omnibus-gitlab package run and paste the output of: \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\`sudo gitlab-rake gitlab:env:info\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\`) (For installations from source run and paste the output of: \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\`sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\`)
Results of GitLab application Check
Expand for output related to the GitLab application check
(For installations with omnibus-gitlab package run and paste the output of: \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\`sudo gitlab-rake gitlab:check SANITIZE=true\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\`) (For installations from source run and paste the output of: \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\`sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production SANITIZE=true\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\`) (we will only investigate if the tests are passing)
Possible fixes
0.1.27+ adds the query string scope=mcp to the request, which likely causes a problem on the GitLab server side for oauth (unexpected parameter?).
-https://gitlab.com/oauth/authorize?response_type=code&client_id=REPLACED&code_challenge=REPLACED&code_challenge_method=S256&redirect_uri=http%3A%2F%2Flocalhost%3A12849%2Foauth%2Fcallback&state=REPLACED
+https://gitlab.com/oauth/authorize?response_type=code&client_id=REPLACED&code_challenge=REPLACED&code_challenge_method=S256&redirect_uri=http%3A%2F%2Flocalhost%3A12849%2Foauth%2Fcallback&state=REPLACED&scope=mcpWorkaround: Pin the mcp-remote module version to 0.1.26 as suggested in #561564 (comment 2720560430) and #566925 (closed)
Patch release information for backports
If the bug fix needs to be backported in a patch release to a version under the maintenance policy, please follow the steps on the patch release runbook for GitLab engineers.
Refer to the internal "Release Information" dashboard for information about the next patch release, including the targeted versions, expected release date, and current status.
High-severity bug remediation
To remediate high-severity issues requiring an internal release for single-tenant SaaS instances, refer to the internal release process for engineers.