GitLab MCP server | GitLab Docs
/ GitLab MCP server Tier : Free, Premium, Ultimate Offering : GitLab.com, GitLab Self-Managed, GitLab Dedicated Status : Generally available Introduced as an experiment in GitLab 18.3 with feature flags named mcp_server and oauth_dynamic_client_registration . Disabled by default. Changed from experiment to beta in GitLab 18.6. Feature flags mcp_server and oauth_dynamic_client_registration removed. Support for 2025-03-26 and 2025-06-18 MCP protocol specifications added in GitLab 18.7.
Support for the 2025-11-25 MCP protocol specification added in GitLab 18.7. Changed to a separate setting and moved from GitLab Premium to GitLab Free in GitLab 19.2. Toolset selection added in GitLab 19.5. duo_agent_platform toolset included by default in GitLab 19.5. Changed from beta to generally available in GitLab 19.5. duo_agent_platform toolset listed only when GitLab Duo Agent Platform is available for the user in GitLab 19.5. code_security tools listed only when the licensed feature behind each tool is available for the user in GitLab 19.5. orbit toolset added in GitLab 19.6.
Server instructions for GitLab Duo flows added in GitLab 19.6. To provide feedback on this feature, leave a comment on issue 630189 . With the GitLab Model Context Protocol (MCP) server, you can securely connect AI tools and applications to your GitLab instance. AI assistants like Claude Desktop, Claude Code, Cursor, and other MCP-compatible tools can then access your GitLab data and perform actions on your behalf. The GitLab MCP server provides a standardized way for AI tools to: Access GitLab project information.
Retrieve issue and merge request data. Interact with GitLab APIs securely. Perform GitLab-specific operations through AI assistants. The GitLab MCP server supports OAuth 2.0 Dynamic Client Registration , which enables AI tools to register themselves with your GitLab instance. When an AI tool connects to your GitLab MCP server for the first time, it: Registers itself as an OAuth application. Requests authorization to access your GitLab data.
Receives an access token for secure API access. For a click-through demo, see GitLab Duo Agent Platform - GitLab MCP server . Prerequisites Allow access to the MCP server: On GitLab.com, for the top-level group . On GitLab Self-Managed and GitLab Dedicated, for the instance . Authentication The GitLab MCP server accepts the following tokens: An OAuth access token with the mcp scope. MCP clients get this token through the OAuth flow when they connect, either with dynamic client registration or with a pre-registered OAuth application .
A fine-grained personal access token with the MCP tool resource and the Execute permission . These tokens cannot have the mcp scope, so the GitLab MCP server rejects them, even with scopes such as api : Legacy personal access tokens Project access tokens Group access tokens If you use one of these tokens, the GitLab MCP server returns 403 Forbidden with the insufficient_scope error. The response names the mcp scope, which you can’t add to these tokens.
Support for these authentication methods is proposed in issue 586184 . Connect a client to the GitLab MCP server The GitLab MCP server supports two transport types: HTTP transport (recommended): Direct connection without additional dependencies. stdio transport with mcp-remote : Connection through a proxy (requires Node.js). Common AI tools support the JSON configuration format for the mcpServers key and provide different methods to configure the GitLab MCP server settings.
To limit which tools the server returns, see Select tool groups (toolsets) . HTTP transport (recommended) Introduced in GitLab 18.6. Tool prefixing added in GitLab 18.11. To configure the GitLab MCP server by using HTTP transport, use this format: Replace <gitlab.example.com> with: On GitLab Self-Managed, your GitLab instance URL. On GitLab.com, gitlab.com . json { "mcpServers" : { "GitLab" : { "type" : "http" , "url" : "https://<gitlab.example.com>/api/v4/mcp" } } } You can add a prefix to tool names by configuring an X-Gitlab-Mcp-Server-Tool-Name-Prefix HTTP header.
Prefixing can help you avoid tool name conflicts with other MCP servers or with multiple GitLab instances in your configuration. The prefix is truncated to the first 32 characters if it exceeds this limit. json { "mcpServers" : { "GitLab" : { "type" : "http" , "url" : "https://<gitlab.example.com>/api/v4/mcp" , "headers" : { "X-Gitlab-Mcp-Server-Tool-Name-Prefix" : "gitlab_" } } } } Select tool groups (toolsets) To limit the tools returned by the GitLab MCP server to specific groups, configure the X-Gitlab-Enabled-Mcp-Server-Toolsets HTTP header with a comma-separated list of toolset names.
For the full list of tools, see the tools reference . Available toolsets: Toolset Included by default meta Always core Yes merge_requests Yes work_items Yes repository Yes ci Yes duo_agent_platform Yes, if GitLab Duo Agent Platform is available wikis No (opt-in) code_security No (opt-in) orbit No (opt-in) The duo_agent_platform tools are listed only when GitLab Duo Agent Platform is available for you. This applies even when you request the toolset in the header or set the header to all .
On GitLab.com, both of the following must be true: You belong to a top-level group on the Premium or Ultimate plan that has GitLab Duo Agent Platform turned on, or you have GitLab Duo Agent Platform through GitLab credits. You are allowed to use GitLab Duo Agent Platform, for example, you have the required seat. On GitLab Self-Managed and GitLab Dedicated, all of the following must be true: GitLab Duo is not set to Always off for the instance.
With Off by default , the tools are listed so that groups that turn GitLab Duo on can use them. The instance has a license that includes GitLab Duo Agent Platform, or has GitLab credits. GitLab Duo Agent Platform is turned on for your organization. You are allowed to use GitLab Duo Agent Platform, for example, you have the required seat. For more information, see the GitLab Duo Agent Platform prerequisites and how to turn GitLab Duo Agent Platform on or off .
When you have access to GitLab Duo Agent Platform, the GitLab MCP server also sends server instructions when your client connects. The instructions tell your AI tool to propose a matching GitLab Duo flow, and to confirm with you before it starts one. They also tell it to check that no flow trigger already runs that flow. The server sends them even when the header leaves out the duo_agent_platform toolset. The code_security tools are listed only when the feature behind each tool is available for you.
This applies even when you request the toolset in the header or set the header to all . list_vulnerabilities , get_vulnerability , and save_vulnerability require the security dashboard. attach_scan_profile requires security scan profiles. Both are Ultimate features. On GitLab.com, the tools are listed if you belong to at least one top-level group on the Ultimate plan, including Ultimate trials. Access to a project in that group also counts.
On GitLab Self-Managed and GitLab Dedicated, the tools are listed if the instance license includes the feature. The orbit toolset has one tool for each Orbit command, for example query_graph . For more information, see Orbit tools . The Orbit server sets the tool names, descriptions, and input schemas. The tools are listed and run only when you meet the Orbit requirements . Orbit tools are listed only when you request the orbit toolset or set the header to all .
Naming an Orbit tool in X-Gitlab-Enabled-Mcp-Server-Tools does not list it. Listing a tool does not grant access. Each tool still checks your project and namespace permissions when called. To include an opt-in toolset, add it to the header value explicitly. To request every toolset, including all opt-in toolsets, set the header to all . When you omit both headers, the server returns the default toolsets. If you omit the toolsets header but set X-Gitlab-Enabled-Mcp-Server-Tool
The rest of this page is on the live site.