GitLab MCP for a homelab without global tokens

The real problem is keeping the connection narrow

Letting an assistant inspect a Laravel repository, a merge request, or a failed pipeline can remove a lot of context switching. The bad version of that setup is pasting a broad personal access token into a local configuration file and forgetting about it. GitLab MCP takes a different route: the client connects to the instance MCP endpoint and authenticates through OAuth, using the permissions of the user who approves the request. (docs.gitlab.com)

GitLab 19.5, released on October 15, 2026, makes the MCP server generally available for GitLab.com, GitLab Self-Managed, and GitLab Dedicated. The official documentation covers clients including Claude Code, Cursor, and OpenAI Codex, all using https://<your-gitlab>/api/v4/mcp. For a homelab GitLab server, that means working directly with the instance without relying on a classic API token carrying the api scope. (docs.gitlab.com)

A practical setup for a Laravel project

The useful case is not asking a model to “read the entire project.” It is giving it a bounded task: inspect a merge request, investigate a failed pipeline, retrieve project metadata, or read one file from CI artifacts. GitLab exposes tools for repositories, merge requests, and CI, and GitLab 19.5 adds get_artifact_file so an agent can retrieve a single artifact file without downloading the full archive. (docs.gitlab.com)

Claude Code can connect over HTTP without an extra proxy. The -s user option makes the server available across that user’s projects, while local scope restricts it to the directory where the configuration was created. After that, start Claude Code, open /mcp, select the server, and approve the OAuth request in the browser. (docs.gitlab.com)

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

Codex also uses HTTP, but the current GitLab instructions require enabling rmcp_client in ~/.codex/config.toml before logging in. Authentication then happens through codex mcp login GitLab, which sends the OAuth approval flow to the self-hosted instance. There is no need to reuse a legacy personal access token: GitLab rejects legacy personal, project, and group access tokens for this endpoint. (docs.gitlab.com)

Fewer tools make for a better configuration

GitLab ships several tool groups by default, including repository, merge_requests, work_items, and ci. For a session focused on Laravel code review and pipeline diagnosis, I do not need to load the full catalog. The X-Gitlab-Enabled-Mcp-Server-Toolsets header accepts a comma-separated list and lets the client request only the groups it needs. (docs.gitlab.com)

This configuration works in clients that accept a headers object, including Cursor. I also added a tool name prefix to avoid collisions when more than one GitLab instance or MCP server is configured in the same client. The prefix changes how tools are named in the client; it does not grant access or alter permissions. (docs.gitlab.com)

{
  "mcpServers": {
    "GitLab homelab": {
      "type": "http",
      "url": "https://gitlab.casa.example/api/v4/mcp",
      "headers": {
        "X-Gitlab-Enabled-Mcp-Server-Toolsets": "repository,ci",
        "X-Gitlab-Mcp-Server-Tool-Name-Prefix": "casa_"
      }
    }
  }
}

The small print matters here

Selecting toolsets limits the tools returned to the client, but it is not an authorization boundary. Every tool still checks the user’s project and namespace permissions when it runs. Also, do not casually combine that header with X-Gitlab-Enabled-Mcp-Server-Tools: GitLab returns the union of both lists, not their intersection. (docs.gitlab.com)

OAuth does not make an agent harmless either. If the authorized account can write to a project, available tools can act with those permissions, and GitLab specifically warns about prompt injection from GitLab objects that the model reads. I would start with trusted projects, a user account without unnecessary privileges, and approval for any action that changes code, issues, or merge requests. (docs.gitlab.com)

There is one operational detail for multi-user instances: OAuth Dynamic Client Registration can create many applications when clients reconnect repeatedly. GitLab supports reusing a pre-registered OAuth application, while each person still authorizes with their own account and receives their own token. If dynamic registration is disabled, that pre-registered application becomes required rather than optional. (docs.gitlab.com)

• Source: GitLab 19.5 release notes
• Official GitLab MCP server documentation