GitLab MCP server: 36 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.

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

This page is one of 90 in a directory of monitoring and developer tools. Each page checks what an AI coding agent can get out of the tool through its MCP server, the connector 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. list_duo_sessions is a genuine oddity: a connector that can see agent runs, provided the agent is GitLab's own.

What can an AI agent do with GitLab?

What connecting costs before the first question

A context window is the amount of text a model can hold at once. Thirty-four tools arrive through GitLab's native endpoint at connection, costing 2,750 to 3,301 tokens on Claude. Eleven of them write.

There is no read-only mode, so the whole list loads or none of it does. One decision covers 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 from the 34 tool entries in the vendor's own documentation. 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?

One tool here reads agent activity, and it reads GitLab’s agents rather than yours. Read from GitLab’s MCP documentation on 25 August 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, and there is no per-tool restriction to fall back on.

5. 5

   Budget for tool descriptions in every request

   Thirty-four tool descriptions arrive at connection, and there is no way to send fewer. 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

Twelve of the 36 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. Eleven of the 34
  tools write. Never call one without asking first.
- That manage_pipeline deletes a pipeline and all related
  data when pipeline_id is the only parameter set.
Never call attach_scan_profile with group_ids. It applies to
every project under the group.
Never 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 are 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

  Eleven tools write, and no setting removes them. 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.

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 runs a public feedback issue for this server. It was open with 312 comments and 12 upvotes when read on 25 August 2026, which makes it one of the few connectors in this directory with genuine public discussion.

“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. 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