doc/user/gitlab_duo/model_context_protocol/mcp_clients.md
{{< details >}}
{{< /details >}}
{{< collapsible title="Model information" >}}
{{< /collapsible >}}
{{< history >}}
duo_workflow_mcp_support. Disabled by default.duo_workflow_mcp_support removed.{{< /history >}}
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 the following environments:
The same MCP configuration file works across all supported IDEs and the GitLab Duo CLI.
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:
<i class="fa-youtube-play" aria-hidden="true"></i> For an overview, see GitLab Duo Chat (agentic) - MCP tool call approval.
<!-- Video published on 2025-06-24 -->For a click-through demo, see GitLab Duo Agent Platform - MCP client.
<!-- Demo published on 2025-08-05 -->For more information about extension support, see version compatibility.
Allow the IDE to access external MCP tools in the top-level group where GitLab Duo is configured.
To allow your local environment to access external MCP tools on GitLab.com:
To allow your local environment to access external MCP tools on GitLab Self-Managed:
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.
| MCP support | GitLab for VS Code | GitLab Duo plugin for JetBrains IDEs | GitLab Duo CLI | |------------------------|-----------------------------------|------------------------|------------------------| | Basic (no workspace or user configuration) | 6.28.2 or later | 3.10.0 or later | | | Full (with workspace and user configuration) | 6.35.6 or later | 3.14.0 or later | 8.81.0 or later |
Workspace configuration applies to this project only, and overrides any user configuration for the same server.
To set up workspace configuration:
<workspace>/.gitlab/duo/mcp.json.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:
Create a configuration file:
{{< tabs >}}
{{< tab title="VS Code or VSCodium" >}}
GitLab MCP: Open User Settings (JSON).{{< /tab >}}
{{< tab title="JetBrains IDEs" >}}
mcp.json file in your home directory:
For Linux or macOS, at ~/.gitlab/duo/mcp.json.
For Windows, at %APPDATA%\GitLab\duo\mcp.json.
For example, C:\Users\<username>\AppData\Roaming\GitLab\duo\mcp.json.
If you have set one of the following environment variables, create the file in a different location:
GLAB_CONFIG_DIR, at $GLAB_CONFIG_DIR/duo/mcp.json.XDG_CONFIG_HOME, at $XDG_CONFIG_HOME/gitlab/duo/mcp.json.{{< /tab >}}
{{< tab title="GitLab Duo CLI" >}}
mcp.json file in your home directory:
For Linux or macOS, at ~/.gitlab/duo/mcp.json.
For Windows, at %APPDATA%\GitLab\duo\mcp.json.
For example, C:\Users\<username>\AppData\Roaming\GitLab\duo\mcp.json.
If you have set one of the following environment variables, create the file in a different location:
GLAB_CONFIG_DIR, at $GLAB_CONFIG_DIR/duo/mcp.json.XDG_CONFIG_HOME, at $XDG_CONFIG_HOME/gitlab/duo/mcp.json.{{< /tab >}} {{< /tabs >}}
Using the configuration format, add information about the MCP servers your feature connects to.
Save the file.
Restart your IDE or the GitLab Duo CLI.
Both configuration files use the same JSON format, with the details in the mcpServers key:
{
"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"
}
}
}
[!note] For other MCP clients, the Atlassian documentation uses
mcp.serversin the sample configuration file. For GitLab, usemcpServersinstead.
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).
[!warning] Only use
"approvedTools": truefor 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"
}
}
}
GitLab uses a two-tier approval system for MCP tools:
mcp.json using the approvedTools field.
These approvals persist across all sessions.A tool is approved if either condition is met.
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.
{
"mcpServers": {
"enterprise-data-v2": {
"type": "stdio",
"command": "node",
"args": ["src/server.js"],
"cwd": "</path/to/your-mcp-server>",
"approvedTools": ["query_database", "fetch_metrics"]
}
}
}
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.
{
"mcpServers": {
"local-http-server": {
"type": "http",
"url": "http://localhost:3000/mcp",
"approvedTools": ["read_file", "write_file"]
}
}
}
{{< history >}}
{{< /history >}}
Prerequisites:
To view the status of your configured MCP servers:
GitLab: Show MCP Dashboard and press <kbd>Enter</kbd>.The MCP dashboard opens in a new editor tab. Use the dashboard to:
To open your MCP configuration files:
GitLab MCP: Open User Settings (JSON) and press <kbd>Enter</kbd>.GitLab MCP: Open Workspace Settings (JSON) and press <kbd>Enter</kbd>.After you update authentication details in an MCP configuration file, you must re-authenticate with the related MCP server.
To trigger re-authentication:
What are the issues in my Jira project? for Atlassian).
The authentication flow starts automatically.{{< history >}}
{{< /history >}}
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.
In the left sidebar, select GitLab Duo Agent Platform ({{< icon name="duo-agentic-chat" >}}).
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:
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.
GitLab caches MCP authentication locally under ~/.mcp-auth/.
To prevent false positives while troubleshooting, delete the cache directory:
rm -rf ~/.mcp-auth/
Error starting server filesystem: Error: spawn ... ENOENTThis 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.
For troubleshooting information, see troubleshooting the GitLab for VS Code extension.