Troubleshooting the GitLab MCP server

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed
  • Status: Experiment

The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.

When working with GitLab MCP server, you might encounter issues.

Troubleshoot the GitLab MCP Server in Cursor

  1. In Cursor, to open the Output view, do one of the following:
    • Go to View > Output.
    • In macOS, press Cmd+ShiftU.
    • In Windows or Linux, press Ctrl+ShiftU.
  2. In the Output view, select MCP:SERVERNAME. The name depends on the MCP configuration value. The example with GitLab results in MCP: user-GitLab.
  3. When reporting bugs, copy the output into the issue template logs section.

Troubleshoot the GitLab MCP Server on the CLI with mcp-remote

  1. Install Node.js version 20 or later.

  2. To test the exact same command as the IDEs and desktop clients:

    1. Extract the MCP configuration.
    2. Assemble the npx command string into one line.
    3. Run the command string.
    rm -rf ~/.mcp-auth/mcp-remote*

npx -y mcp-remote@latest https://gitlab.example.com/api/v4/mcp --static-oauth-client-metadata '{"scope": "mcp"}'

  3. Add the --debug parameter to log more verbose output:

    rm -rf ~/.mcp-auth/mcp-remote*

npx -y mcp-remote@latest https://gitlab.example.com/api/v4/mcp --static-oauth-client-metadata '{"scope": "mcp"}' --debug

  4. Optional. Run the mcp-remote-client executable directly.

    rm -rf ~/.mcp-auth/mcp-remote*

npx -p mcp-remote@latest mcp-remote-client https://gitlab.example.com/api/v4/mcp --static-oauth-client-metadata '{"scope": "mcp"}'

  5. Optional. If you encounter version-specific bugs, pin the version of the mcp-remote module to a specific version. For example, use mcp-remote@0.1.26 to pin the version to 0.1.26.

    For security reasons, you should not pin versions if possible.

Troubleshoot GitLab MCP Server with Claude Desktop

Verify the installed Node.js versions. Claude Desktop requires Node.js version 20 or later.

for n in $(which -a node); do echo "$n" && $n -v; done

Delete MCP authentication caches

The MCP authentication is heavily cached locally. While troubleshooting, you might encounter false positives. To prevent these, delete the cache directory during troubleshooting:

rm -rf ~/.mcp-auth/mcp-remote*

Debugging and development tools

MCP Inspector is an interactive developer tool for testing and debugging MCP servers. To run this tool, use the command line and access the web interface to inspect the GitLab MCP Server.

npx -y @modelcontextprotocol/inspector npx