GitLab MCP clients

Tier: Premium, Ultimate
Add-on: GitLab Duo Core, Pro, or Enterprise
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
Status: Beta

The Model Context Protocol (MCP) provides a standardized way for GitLab Duo features to securely connect to different external data sources and tools.

MCP is supported in:

Visual Studio Code (VS Code) and VSCodium
JetBrains IDEs

The same MCP configuration file works across all supported IDEs.

The following features can act as MCP clients and connect to external tools from MCP servers:

These features can then access external context and information to generate more powerful answers.

To use a feature with MCP:

Turn on MCP for your group.
Configure the MCP servers you want the feature to connect to.

For a click-through demo, see GitLab Duo Agent Platform - MCP integration.

Prerequisites

Before using a GitLab Duo feature with MCP, you must:

Meet the prerequisites for the GitLab Duo Agent Platform.

In addition, for VS Code:

Install VSCodium or Visual Studio Code (VS Code).
Set up the GitLab Workflow extension from the Open VSX Registry or the Visual Studio Marketplace.
- MCP support requires version 6.28.2 and later.
- Workspace and user configuration features require version 6.35.6 and later.

For JetBrains IDEs:

Install a JetBrains IDE.
Install and set up the GitLab Duo plugin for JetBrains IDEs.

Turn on MCP for your group

To turn MCP on or off for your group:

On the left sidebar, select Search or go to and find your group. If you’ve turned on the new navigation, this field is on the top bar.
Select Settings > GitLab Duo.
Select Change configuration.
Under Model Context Protocol, select or clear the Turn on Model Context Protocol (MCP) support checkbox.
Select Save changes.

Configure MCP servers

To integrate MCP with the Language Server, set up workspace configuration, user configuration, or both. The GitLab Language Server loads and merges the configuration files.

Version compatibility

GitLab Workflow extension version	MCP features available
6.28.2 - 6.35.5	Basic MCP support, with no workspace or user configuration
6.35.6 and later	Full MCP support, including workspace and user configuration

Create workspace configuration

Workspace configuration applies to this project only, and overrides any user configuration for the same server.

To set up workspace configuration:

In your project workspace, create the file <workspace>/.gitlab/duo/mcp.json.
Using the configuration format, add information about the MCP servers your feature connects to.
Save the file.
Restart your IDE.

Create user configuration

User configuration settings are good for personal tools and commonly-used servers. They apply to all workspaces, but any workspace settings for the same server override the user configuration.

To set up user configuration:

In VSCodium or VS Code, open the Command Palette by pressing Control+Shift+P or Command+Shift+P.
Run the command GitLab MCP: Open User Settings (JSON) to create and open the user configuration file.
Using the configuration format, add information about the MCP servers your feature connects to.
Save the file.
Restart your IDE.

For JetBrains IDEs, or to manually create the file in VS Code, use this location:

Windows: C:\Users\<username>\AppData\Roaming\GitLab\duo\mcp.json
All other operating systems: ~/.gitlab/duo/mcp.json

Configuration format

Both configuration files use the same JSON format:

{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "path/to/server",
      "args": ["--arg1", "value1"],
      "env": {
        "ENV_VAR": "value"
      },
      "approvedTools": true
    },
    "http-server": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "approvedTools": ["read_file", "search"]
    },
    "sse-server": {
      "type": "sse",
      "url": "http://localhost:3000/mcp/sse"
    }
  }
}

Configure tool approval

By default, in each session you must manually approve every MCP tool from your server.

Instead, you can pre-approve MCP tools in your configuration file to skip manual approval prompts.

To do so, add the approvedTools field to any server configuration:

"approvedTools": true - Automatically approve all current and future tools from this server.
"approvedTools": ["tool1", "tool2"] - Approve only the tools you have specified.

If you do not include this field, you must manually approve every tool in the session (this is the default behavior).

Only use "approvedTools": true for servers you completely trust.

For example:

{
  "mcpServers": {
    "trusted-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["my-trusted-mcp-server"],
      "approvedTools": true
    },
    "selective-server": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "approvedTools": ["read_file", "search"]
    },
    "untrusted-server": {
      "type": "sse",
      "url": "http://example.com/mcp/sse"
    }
  }
}

How tool approval works

GitLab uses a two-tier approval system for MCP tools:

Configuration-based approval (permanent): Tools approved in mcp.json using the approvedTools field. These approvals persist across all sessions.
Session-based approval (temporary): Tools approved during runtime for the current workflow session. These approvals are cleared when you close your IDE or end the workflow.

A tool is approved if either condition is met.

Example MCP server configurations

Use the following code examples to help you create your MCP server configuration file.

For more information and examples, see the MCP example servers documentation. Other example servers are Smithery.ai and Awesome MCP Servers.

Local server

{
  "mcpServers": {
    "enterprise-data-v2": {
      "type": "stdio",
      "command": "node",
      "args": ["src/server.js"],
      "cwd": "</path/to/your-mcp-server>",
      "approvedTools": ["query_database", "fetch_metrics"]
    }
  }
}

GitLab Knowledge Graph server

The GitLab Knowledge Graph provides code intelligence through MCP. You can approve all tools or specific ones:

{
  "mcpServers": {
    "knowledge-graph": {
      "type": "sse",
      "url": "http://localhost:27495/mcp/sse",
      "approvedTools": true
    }
  }
}

Or approve only specific tools:

{
  "mcpServers": {
    "knowledge-graph": {
      "type": "sse",
      "url": "http://localhost:27495/mcp/sse",
      "approvedTools": ["list_projects", "search_codebase_definitions", "get_references", "get_definition"]
    }
  }
}

For more information about available tools, see the Knowledge Graph MCP tools documentation.

HTTP server

{
  "mcpServers": {
    "local-http-server": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "approvedTools": ["read_file", "write_file"]
    }
  }
}

Use GitLab Duo features with MCP

When a GitLab Duo feature calls an external tool to answer a question, you must review that tool unless you’ve approved it for the entire session:

Open VS Code.
On the left sidebar, select GitLab Duo Agent Platform (Beta) ( ).
Select the Chat or Flows tab.
In the text box, enter a question or specify a code task.
Submit the question or code task.
The Tool Approval Required dialog appears in these cases:
- GitLab Duo is calling that tool for the first time in your session.
- You have not approved that tool for the entire session.
Approve or deny the tool:
- If you approve the tool, the feature connects to the tool and generates an answer.
  - Optional. To approve the tool for the entire session, from the Approve dropdown list, select Approve for Session.
    You can approve only MCP server-provided tools for the session. You cannot approve terminal or CLI commands.
- For Chat, if you deny the tool, the Provide Rejection Reason dialog appears. Enter a rejection reason, then select Submit Rejection.
  Chat might take action based on the reason you provide, such as suggesting a new approach, or creating an issue.

Troubleshooting

`Error starting server filesystem: Error: spawn ... ENOENT`

This error occurs when you specify a command using a relative path (like node instead of /usr/bin/node), and that command cannot be found in the PATH environment variable that was passed to the GitLab Language Server.

Improvements to resolving PATH are tracked in issue 1345.

Troubleshooting MCP in VS Code

For troubleshooting information, see troubleshooting the GitLab Workflow extension for VS Code.