GitLab MCP server: 56 tools, no read-only mode

What the native endpoint exposes, why one tool deletes a pipeline when you leave a parameter out, and why teams in GitLab's own feedback issue run a community server instead.

Checked 25 August 2026 · from docs.gitlab.com, the live endpoint and feedback issue 561564

One of 91 guides to monitoring and developer tools. Each covers what an AI coding agent can get out of the tool through MCP, the protocol that lets the agent query the tool directly.

What is the GitLab MCP server?

GitLab holds the repository, the merge requests, the issues, the work items and the CI pipelines. An MCP server over it lets an agent read a diff, look at why a job failed and comment on a review without a browser.

GitLab built the endpoint into the product rather than shipping a package. It arrived as an experiment in 18.3 behind two feature flags. Those flags were removed in 18.6, when it became beta. It gained the 2025-03-26 and 2025-06-18 protocol specifications in 18.7. It moved from Premium to Free in 19.2.

Authentication is OAuth 2.0 Dynamic Client Registration only. The client registers itself, a browser opens, you approve, and a token comes back. Personal access tokens are not accepted, which is the single most requested change in the feedback issue.

GitLab covers code review and CI outright, and reaches agent observability in a way almost no other connector does. It carries no production telemetry and no spend data.

For an agent, that means GitLab answers the whole path from a diff to the pipeline that tested it, and nothing about what happened after deploy. The Duo tools are a genuine oddity: a connector that can start, watch and steer agent runs, provided the agent is GitLab's own.

What can an AI agent do with GitLab?

What the tool definitions cost in context

A client that loads every tool definition at the start of a session spends this much context before the first question. Claude Code defers definitions by default through tool search, and loads a tool's definition when the agent needs it. The method below gives the version and date measured.

A context window is the amount of text a model can hold at once. On 25 August 2026 the 34 documented tools cost 2,750 to 3,301 tokens on Claude. The reference now lists 47 tools, so the current figure is higher.

From GitLab 19.5, toolset and tool headers can shrink the list. One choice of headers sets both the context cost and the write exposure.

Encodings: GPT-5.6, GPT-5.5 o200k_base; GPT-4, GPT-3.5 cl100k_base; Claude Haiku 4.5 to Opus 5 count_tokens. Counted on 25 August 2026 from the 34 tool entries the vendor's documentation listed then. That documentation is the only public inventory.

The server could not be run for a live tools/list. So no input schemas are available, and these figures cover each tool's name and description only. They are a floor, not the figure.

The Claude columns are measured through the API's count_tokens endpoint with an empty schema per tool. So they cover the same content as the GPT columns. The range there is two tokenizer generations. Haiku 4.5 and Opus 4.6 are at the low end. Opus 5 and Sonnet 5 are at the high end. The gap between them is about a fifth.

Can GitLab watch your own AI agents?

Five Duo Agent Platform tools reach agent activity, and they reach GitLab’s agents rather than yours. Read from GitLab’s MCP documentation on 6 October 2026.

GitLab MCP server limits: where answers come back incomplete

One tool deletes a pipeline when a parameter is left out. Read that limit before the rest.

How to configure GitLab MCP for agents

1. 1

   Turn on three settings, not one

   Duo availability must be Always on or On by default, beta and experimental features must be on, and access to the MCP server must be allowed. All three sit at the top-level group on GitLab.com, or the instance elsewhere.

2. 2

   Choose HTTP transport

   GitLab recommends it and it needs no Node.js. The stdio route runs npx mcp-remote and requires Node 20 or later.

3. 3

   Prefix the tool names if you run more than one GitLab

   The X-Gitlab-Mcp-Server-Tool-Name-Prefix header, added in 18.11, renames every tool for that connection. It truncates at 32 characters.

4. 4

   Decide what the OAuth identity may do before connecting

   The token carries your own permissions. Narrowing the tool list limits what the agent can call, and the token keeps its full reach.

5. 5

   Budget for tool descriptions in every request

   Every listed tool description arrives at connection unless you narrow the list. GitLab 19.5 adds X-Gitlab-Enabled-Mcp-Server-Toolsets to pick toolsets and X-Gitlab-Enabled-Mcp-Server-Tools to pick tools by name. An engineer in the feedback issue reports the agent trying several wrong tools before finding the right one.

Paste this into your agent’s instructions

Fifteen of the 47 listed tools write, and the write and read names look alike. The block forces the agent to say which side of that line it crossed.

When you answer using GitLab MCP tools, state:
- Which tool you called and the project it acted on.
- Whether the call was a read or a write. Fifteen of the 47
  listed tools write. Ask before you call one.
- That manage_pipeline deletes a pipeline and all related
  data when pipeline_id is the only parameter set.
Do not call attach_scan_profile with group_ids. It applies to
every project under the group.
Do not state that data does not exist. State which tool you
called and what it returned.
Write your answer in ASD-STE100 Simplified Technical
English. Use short sentences with one idea in each.

Do you need the MCP server at all?

Not for unattended work. glab, GitLab's own CLI, is the alternative teams actually reach for. On 18 March 2026 an engineer reported more success with it than with the MCP server or third-party wrappers, and fewer tokens spent.

Community servers are the other route, and the feedback issue documents real migrations to them. They trade official support for fine-grained tokens, selectable toolsets and separate read-only endpoints.

The v4 REST API remains the direct path for anything scheduled. The MCP endpoint is that same API with tool descriptions attached.

For the code review itself, SonarQube, Semgrep and CodeRabbit answer questions about the diff that GitLab's own tools do not.

With MCP, one connection reaches the diff, the pipeline that tested it and the discussion about it, with no token to place in a config file.

Use the native endpoint for interactive work. Use glab or the REST API for anything that runs unattended.

GitLab MCP server setup

Nothing is installed. The endpoint is https://<gitlab.example.com>/api/v4/mcp, and on GitLab.com that host is gitlab.com.

No configuration block below holds a credential. Authentication is OAuth 2.0 Dynamic Client Registration: the client registers itself on first connect, a browser opens the authorize page, and you approve it there.

Before any of it works, three settings must be on: Duo availability set to Always on or On by default, beta and experimental features enabled, and access to the MCP server allowed. On GitLab.com they live on the top-level group; on Self-Managed and Dedicated they live on the instance.

claude mcp add --transport http GitLab https://gitlab.com/api/v4/mcp

{"mcpServers":{"GitLab":{"type":"http",
  "url":"https://gitlab.com/api/v4/mcp"}}}

[features]
rmcp_client = true

[mcp_servers.GitLab]
url = "https://gitlab.com/api/v4/mcp"

{"mcpServers":{"GitLab":{"type":"http",
  "url":"https://gitlab.example.com/api/v4/mcp",
  "headers":{
    "X-Gitlab-Mcp-Server-Tool-Name-Prefix":"gitlab_"}}}}

Every other client

Each block below is the configuration for one client, with the file path and the key that client expects.

{"mcpServers":{"GitLab":{"command":"npx",
  "args":["-y","mcp-remote",
    "https://gitlab.com/api/v4/mcp"]}}}

{"mcpServers":{"GitLab":{
  "httpUrl":"https://gitlab.com/api/v4/mcp"}}}

{"servers":{"GitLab":{"type":"http",
  "url":"https://gitlab.com/api/v4/mcp"}}}

{"mcpServers":{"GitLab":{"serverUrl":
  "https://gitlab.com/api/v4/mcp"}}}

{"context_servers":{"GitLab":{
  "url":"https://gitlab.com/api/v4/mcp"}}}

{"mcpServers":{"GitLab":{"type":"http",
  "url":"https://gitlab.com/api/v4/mcp"}}}

{"amp.mcpServers":{"GitLab":{
  "url":"https://gitlab.com/api/v4/mcp"}}}

{"mcpServers":{"GitLab":{"type":"streamableHttp",
  "url":"https://gitlab.com/api/v4/mcp"}}}

extensions:
  gitlab:
    type: streamable_http
    uri: https://gitlab.com/api/v4/mcp

{"mcpServers":{"GitLab":{"command":"npx",
  "args":["-y","mcp-remote",
    "https://gitlab.com/api/v4/mcp"]}}}

{"mcpServers":{"GitLab":{
  "url":"https://gitlab.com/api/v4/mcp"}}}

{"mcpServers":{"GitLab":{"type":"http",
  "url":"https://gitlab.com/api/v4/mcp"}}}

{"mcpServers":{"GitLab":{"type":"streamable-http",
  "url":"https://gitlab.com/api/v4/mcp"}}}

name: GitLab
version: 0.0.1
schema: v1
mcpServers:
  - name: GitLab
    type: streamable-http
    url: https://gitlab.com/api/v4/mcp

{"mcpServers":{"GitLab":{
  "url":"https://gitlab.com/api/v4/mcp"}}}

{"mcpServers":{"GitLab":{"type":"http",
  "url":"https://gitlab.com/api/v4/mcp"}}}

claude mcp add --transport http GitLab \
  https://gitlab.example.com/api/v4/mcp

Read-only access, permissions and security

• GitLab puts prompt injection on you, in writing

  The documentation repeats, once per client: You're responsible for guarding against prompt injection when you use these tools. Exercise extreme caution or use MCP tools only on GitLab objects you trust. An issue description is untrusted text that reaches the model.

• There is no read-only mode

  Fifteen listed tools write. From GitLab 19.5, the X-Gitlab-Enabled-Mcp-Server-Tools header can name read tools alone. The comparison teams keep drawing in the feedback issue is GitHub's separate read-only endpoint.

• manage_pipeline deletes by omission

  Per the documentation, if pipeline_id is the only parameter set, the call deletes the pipeline and all related data. Adding a name makes the same call a rename.

• attach_scan_profile accepts group IDs

  One call attaches a security scan profile to every project under a group, so a single mistake reaches a whole namespace rather than one repository.

• The token is you

  OAuth grants the connection your own permissions across every project you can reach, and there is no narrower scope to hand it.

• Personal access tokens are refused

  That removes a class of leaked-secret risk and rules out machine-to-machine use, which is why several teams in the feedback issue run a community server with fine-grained tokens instead.

Troubleshooting

403 when authenticating with a personal access token

Expected. A GitLab engineer confirmed in the feedback issue that the server supports OAuth-granted tokens only, and that PATs are not supported.

The server does not appear at all

Check all three prerequisites, not just one: Duo availability, beta and experimental features, and MCP server access. Missing any leaves the endpoint invisible.

`InvalidGrantError` or an expired authorization grant

The mcp-remote proxy caches OAuth state in ~/.mcp-auth. Clearing it forces a fresh authorization, and also signs out every other MCP server that uses that directory.

`Server's protocol version is not supported`

Reported against Claude Desktop 0.13.91 in the feedback issue. GitLab added the 2025-03-26 and 2025-06-18 protocol specifications in 18.7, so an older instance will not negotiate with a newer client.

A tool name from an older guide no longer exists

Names moved during beta. gitlab_search became search in 18.8, get_job_log became get_job in 19.3 and is kept as an alias, and manage_pipeline lost list, create, retry and cancel to list_pipelines and save_pipeline in 19.3.

semantic_code_search became semantic_search in 19.4 and is kept as an alias. Nine superseded tools are unlisted in 19.4 and 19.5, and stay callable while callers migrate.

The job log is cut off

It is a window, not a truncation. get_job returns at most byte_limit bytes, default and maximum 512000, and the response reports the total size and the byte_offset for the next window.

GitLab MCP server: Reference

What engineers report

GitLab ran a public feedback issue for this server. Issue 561564 closed on 22 September 2026 with 407 comments and 12 upvotes. That makes it one of the few connectors in this directory with genuine public discussion. GitLab's documentation now points feedback to issue 630189, opened 21 September 2026.

“Currently the MCP server only supports OAuth-granted tokens. PATs are not supported.”

“I've found that tools like claude code often work better with a CLI. I've experienced a lot more success using the GitLab CLI with claude code than with the MCP (even 3rd party MCPs that wrap the GitLab API). It not only accomplish tasks a lot easier, it also uses less tokens.”

“I talked about the vague / broad permissions here. I've resorted to using a community MCP w/ fine-grained tokens. It also seems more stable, and can just add tools / features as needed easily.”

“When using the community server to get a discussion note (comment on MR), the agent does it straightforward. When using this official MCP, it explores unrelated tools like workitem, then it tries curl. Finally after many tokens burned, it uses search which sounds pretty suboptimal.”

“For each GitLab MCP tool, I would want to see: read-only vs mutating, required token scopes, whether it can affect CI/CD, issues, merge requests, repository content, or settings. This matters because agents often choose tools from names/descriptions, not from full docs.”

Comments were read from the public discussion on issue 561564 on 25 August 2026. Its state and comment count were read from the GitLab API on 6 October 2026. Author names and dates are as recorded on each comment. Quotes are trimmed for length and links inside them are described rather than reproduced.

Should you connect an agent to GitLab?

Yes. Best for interactive review and CI triage, with writes approved at the client.

Strongest fit

Teams already on GitLab who want an agent reading merge requests and pipeline failures without installing or maintaining anything.

Main advantage

There is no package, no token in a config file and no separate update path. Upgrading GitLab is the whole install.

Main weakness

No read-only mode, no personal access tokens, and a tool list that renamed and removed tools during beta.

Operational risk

manage_pipeline deletes a pipeline and all related data when pipeline_id is its only parameter.

Frequently asked questions