Dev.to AI πŸ€– Ai πŸ‘ 0 πŸ“– 9 min read

Inside a GitLab MCP Fork: CQRS, Context Efficiency and Self-Hosted GitLab

How do you give an AI coding agent access to GitLab without filling its context window with tools it will never call? That question is behind @structured-world/gitlab-mcp, an open-source GitLab MCP server maintained by D

Inside a GitLab MCP Fork: CQRS, Context Efficiency and Self-Hosted GitLab

How do you give an AI coding agent access to GitLab without filling its context window with tools it will never call? That question is behind @structured-world/gitlab-mcp, an open-source GitLab MCP server maintained by Dmitry Prudnikov. This post explains the reasoning behind the project and its limits. The design reasoning comes from the maintainer and the project's documentation. The testing is mine: I set the server up from scratch on a new project and had an agent investigate a failed pipeline, and each section below ties back to that task. Results are from version 12.1.0 unless I say otherwise.

Full disclosure: the maintainer commissioned this write-up. The test steps, results and limits are reported as I found them.

The project's aim isn't simply to expose fewer tools. It's to expose a more relevant set of tools and actions for the GitLab instance, permissions and workflow at hand.

Where this started

The project grew out of zereight/gitlab-mcp, and that deserves saying plainly. The original gave many people a working GitLab integration for MCP clients early on, and it is still active. The project's package manifest lists zereight as the original author. The README states the project is based on zereight/gitlab-mcp (MIT), and the repository keeps the original MIT license file (LICENSE.MIT) next to its Apache-2.0 license.

The fork didn't start because something was broken. The maintainer wanted to try a different answer to three questions:

  1. How many tool definitions does an agent really need to see?
  2. How should a server behave across different GitLab installations, from a free self-managed box to an Ultimate instance?
  3. Should reading and changing data look like the same kind of thing to the model?

The context problem, stated carefully

An MCP client typically sends the server's tool list to the model at session start. Every tool name, description and input schema takes prompt space before you type anything. A server that mirrors the GitLab API one endpoint per tool can end up with a very large list. Keeping that list small is what people mean by MCP context optimization, and there are several workable ways to do it. The original project now ships a lean default set, and GitLab's own MCP server, generally available since GitLab 19.5, lets you choose toolsets. This project's approach is to group related operations into fewer tools.

In my 12.1.0 test, the agent made six tool calls to answer the question, and Claude Code showed 35 tools for the server. But the size of the list is only half the story: the results it got back were often larger than the question needed. I come back to that below.

Browse and manage: the CQRS part

CQRS (Command Query Responsibility Segregation) means keeping operations that read data separate from operations that change it. In this server it shows up as a naming convention: browse_* tools are read-only queries, manage_* tools are writes, and related operations are folded into typed actions inside one tool. Pipelines, for example: browse_pipelines covers listing pipelines, listing jobs and reading job logs, and manage_pipeline covers triggering, retrying and canceling.

The 12.1.0 README says the server has 64 tools exposing 235 GitLab operations across 26 entity types, because sub-resources fold into actions instead of becoming new tools. Tool count and operation count are different numbers: a smaller tool count doesn't mean less functionality, and it doesn't automatically mean fewer tokens.

Why split reads from writes? Permissions become legible, and the model gets a predictable shape. In the 12.1.0 test the split was visible: the agent's calls were browse_merge_requests and browse_pipelines with the actions list, jobs and logs, and a newcomer reading the transcript could tell which calls only looked.

Capability filtering: only offer what the instance can do

This matters most for self-hosted users. Version, tier, token scopes and admin state all change what GitLab's API will accept. If a server advertises something your instance lacks, the agent tries it and gets an error, which costs a round trip and can send the model down a wrong path.

In the 12.1.0 source, the server works out what the instance and token can do and shapes the tool list accordingly:

  • Version: GitLab 16.0 and later is supported. Tools needing a higher version are hidden on older instances.
  • Tier: Free < Premium < Ultimate. An Ultimate-only action isn't advertised on Free.
  • Token scopes: tools the token can't use are filtered out.
  • Admin state: admin-only tools depend on whether admin mode is active.
  • Configuration: feature flags, a deny-list regex and read-only mode can remove tools.

Two caveats. When the instance version can't be determined, version and tier checks fail open (the tool is shown), so filtering is best-effort. And capability detection is not authorization: GitLab still enforces its own permission checks on every call.

My test showed the scope part in practice, which I describe below. It did not exercise version or tier differences, because it ran on one gitlab.com account.

A concrete example: investigating a failed pipeline

The setup. I created a brand-new project on gitlab.com with a merge request whose pipeline fails on purpose: one CI job prints "Expected 5 but got 4" and then runs exit 1. I created a personal access token with only the read_api scope, so the agent could read but not change anything. My environment was Windows, Node 24 and Claude Code 2.1.312, connected with one command (replace YOUR_TOKEN with your own, and paste it as a single line):

claude mcp add gitlab --transport stdio --scope user --env GITLAB_TOKEN=YOUR_TOKEN --env GITLAB_API_URL=https://gitlab.com -- cmd /c npx -y @structured-world/[email protected]

The first setup took about 30 minutes, almost all of it GitLab rather than the MCP server. GitLab asked me to verify my identity before running my first pipeline (a puzzle and a card check; the screen said there is no charge). My first CI file showed as invalid, and a simpler one fixed it. And my first paste of the connect command split across two lines and failed until I pasted it as one line.

One snag was on the MCP side. I first ran 12.0.3, which worked. When I switched to 12.1.0, Claude Code reported the server as failed (CONNECTION_CLOSED), and running it by hand printed this:

'gitlab-mcp' is not recognized as an internal or external command

Clearing the npm cache and deleting the _npx cache folder fixed it. 12.0.3 had worked before, so I suspect a damaged cache on my machine, but I haven't confirmed the cause.

Windows terminal showing the error 'gitlab-mcp' is not recognized as an internal or external command

The error on the first launch of 12.1.0 on Windows, which persisted after npm cache clean --force; deleting the _npx cache folder was also needed.

Earlier runs on 12.0.3. I gave the agent this prompt:

Use the gitlab tools to look at the project. The pipeline on merge request !1 failed. Find out why, and tell me which job failed, what the log says, and how to fix it. Don't change anything.

On Opus 5.5, the agent made four GitLab calls and answered in 20 seconds. It named the failed job, quoted the log, and said the cause was the hard-coded exit 1: "Expected 5 but got 4" was only text printed by echo, not a real test failing. On Sonnet 5.5, it made five calls, and the last one failed: it guessed the action read for browse_files, and the server's error listed the valid ones (tree, content and download_attachment). It didn't retry, said so, and still reached the same diagnosis from the log.

The run on 12.1.0. I repeated the prompt on Sonnet 5.5 at Medium effort. This time the agent made six calls in 29 seconds and none failed. It first checked the server (manage_context with show, then get_settings), then called browse_merge_requests, and then browse_pipelines with list, jobs and logs. The answer matched the earlier ones: job test in pipeline #3006110038 failed with script_failure, because the script ends with exit 1. It told me to remove that line or replace it with a real test command. It also said it had only read the log, not the CI file, and offered to open it.

Claude Code's answer on 12.1.0: the log shows exit 1, and the fix is to remove it or replace it with a real test command

The agent's answer on 12.1.0 (the end of the reply), as it appeared in Claude Code.

When it needed to write. On 12.0.3 I asked the agent to retry the failed job. It didn't. It called manage_context with list_presets, which returned 13 built-in presets, said it saw no retry tool, and asked permission before switching presets. I said no, and nothing changed. The agent's suggestion that a preset like devops would add a retry tool was its guess, and I didn't test it.

What the 12.1.0 run showed is more precise. The server's settings said preset none and read-only mode off. Its startup log said the token had limited scopes (scopes=read_api) and that only some of the scope-gated tools were available. Claude Code then listed 35 tools: 28 browse_* tools, seven helper tools, and no write tool for GitLab data. The only manage_* tool was manage_context, which changes the server's own settings. So the read-only token is the likely reason there was nothing to retry with. I haven't tested a write-scope token, so I can't prove it.

Server startup log line showing the token has limited scopes, scopes=read_api

The server's startup log on 12.1.0. Its counts (32 of 58) come from the server's table of scope-gated tools, not from the 64 tools in the README or the 35 Claude Code listed.

First 21 of the 35 tools Claude Code listed for the GitLab server

Last 14 of the 35 tools Claude Code listed, with manage_context as the only manage tool

The 35 tools Claude Code listed for the server on 12.1.0 (two screenshots). Only manage_context is a `manage_` tool.*

What this does and doesn't buy you

Grouping has a cost. Each tool has several actions, and Sonnet guessed one wrong on 12.0.3. The error listed the valid options, but a retry would have been better than giving up on the file.

A short tool list also doesn't make a short conversation. The merge request and job calls returned long JSON, including user profiles and runner details, just to report that one job failed. I didn't measure tokens, so I don't have a defensible percentage for savings, and I'd be skeptical of anyone who quotes one without a method. To compare servers, hold the client, model, GitLab version, token and task constant, and measure tool-schema tokens separately from total task tokens.

The limits are real. This was one small project on gitlab.com, a read-only token, and one run per model and version. It says nothing about self-managed GitLab, older versions, other tiers or large repositories, which is where filtering matters most.

Who this is for. If you run a self-managed instance with mixed versions or tiers, or you want write tools to stay out of the agent's reach unless the token allows them, the filtering is aimed at you. If you only need a few read operations on a recent gitlab.com project, a smaller tool set may be all you need. Test it on your own instance before relying on this write-up.

Trying it

For local use with a client like Claude Code or Cursor, the server runs through npx:

npx -y @structured-world/gitlab-mcp

To reproduce my results, pin the version I tested:

npx -y @structured-world/[email protected]

Node.js 24 or newer is required. The README links setup guides for Claude Code, Codex, Cursor, VS Code, Windsurf and Cline, among others. Start with a read_api token, set a short expiry, and revoke it when you finish. If the first launch on Windows fails with 'gitlab-mcp' is not recognized, clear the npm cache and the _npx folder and try again. The README's quick start for an MCP client config looks like this:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@structured-world/gitlab-mcp"],
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "https://gitlab.com"
      }
    }
  }
}

There is also a Docker image (ghcr.io/structured-world/gitlab-mcp:latest) that runs in HTTP or stdio mode. Configuration can change between releases, so check the project documentation against the version you install. If something doesn't behave, open an issue. The code is public, so you can also read how a tool decides what to show.

πŸ“° Read the original article on Dev.to AI

Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes β€” full credit and traffic to the original publisher.