From 0c7d798aa9fa4ea612633d363c07719028d92744 Mon Sep 17 00:00:00 2001 From: Jonathan Glassman Date: Mon, 1 Sep 2025 08:11:38 +0100 Subject: [PATCH 1/2] Update mcpservers code snippet --- doc/user/gitlab_duo/model_context_protocol/mcp_server.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/user/gitlab_duo/model_context_protocol/mcp_server.md b/doc/user/gitlab_duo/model_context_protocol/mcp_server.md index 6069db205897c0..960778dee352bd 100644 --- a/doc/user/gitlab_duo/model_context_protocol/mcp_server.md +++ b/doc/user/gitlab_duo/model_context_protocol/mcp_server.md @@ -66,9 +66,10 @@ To do this: "mcpServers": { "GitLab": { # If npx is installed locally, not globally, provide the full path - "command": "npx", + "command": "/opt/homebrew/bin/npx", "args": [ - "mcp-remote", + "-y", + "mcp-remote@0.1.24", "https://your-gitlab-instance.com/api/v4/mcp" ] } -- GitLab From ef8a29e22357cb6e35f85803ed6d54a34b979389 Mon Sep 17 00:00:00 2001 From: Jonathan Glassman Date: Mon, 1 Sep 2025 11:46:27 +0100 Subject: [PATCH 2/2] Add troublshooting entry and supporting info --- .../model_context_protocol/mcp_server.md | 32 +++++++++++++++++-- 1 file changed, 29 insertions(+), 3 deletions(-) diff --git a/doc/user/gitlab_duo/model_context_protocol/mcp_server.md b/doc/user/gitlab_duo/model_context_protocol/mcp_server.md index 960778dee352bd..65cce8807a610f 100644 --- a/doc/user/gitlab_duo/model_context_protocol/mcp_server.md +++ b/doc/user/gitlab_duo/model_context_protocol/mcp_server.md @@ -59,17 +59,21 @@ To do this: 1. Open Cursor. 1. In Cursor, go to **Settings** > **Cursor Settings** > **Tools & Integrations**. 1. Under **MCP Tools**, select `New MCP Server`. -1. Add this definition to the `mcpServers` key, editing the value of `mcp-remote` as needed: +1. Add this definition to the `mcpServers` key, editing the value of: + - `mcp-remote` as needed. + - `"command"` to work with your operating system and package manager. + For example, if you use macOS with Homebrew, you might have to change + it to `"command": "/opt/homebrew/bin/npx"`. ```json { "mcpServers": { "GitLab": { # If npx is installed locally, not globally, provide the full path - "command": "/opt/homebrew/bin/npx", + "command": "", "args": [ "-y", - "mcp-remote@0.1.24", + "mcp-remote", "https://your-gitlab-instance.com/api/v4/mcp" ] } @@ -213,3 +217,25 @@ Show me all pipelines for merge request 42 in project gitlab-org/gitlab ## Feedback This feature is experimental. Your feedback is valuable in helping us to improve it. Share your experiences, suggestions, or issues in [issue 561564](https://gitlab.com/gitlab-org/gitlab/-/issues/561564). + +## Troubleshooting + +### OAuth callback error + +When the MCP client creates the authentication callback with the OAuth URL, you might +get an error that states the following: + +```plaintext +An error has occurred + +The requested scope is invalid, unknown, or malformed. +``` + +This error means that you cannot authenticate against the GitLab MCP server, and +blocks you from any further use of the server. + +The workaround for this error is to, when you [configure the `mcpServers` key](#connect-cursor-to-a-gitlab-mcp-server), pin the `mcp-remote` version to `0.1.26`. +For example,`"mcp-remote@0.1.26"`. + +[Issue 566965](https://gitlab.com/gitlab-org/gitlab/-/issues/566965) exists to +investigate this error. -- GitLab