How to connect a GitLab MCP to Cursor (4 steps)

When you're building a triage bot, automating issue routing, or writing a CI failure handler, you need to see real issue structures, live merge request metadata, and actual pipeline job output to write logic that handles what GitLab actually produces.

Getting that data means leaving Cursor, navigating GitLab, running test API calls, and copying results back into the editor.

To help your developers query GitLab repository, issue, and pipeline data without leaving Cursor, we'll show you how to connect GitLab with Merge Agent Handler's GitLab MCP server.

How it works

Merge Agent Handler connects Cursor to the GitLab API through the Merge CLI.

Install the CLI, authenticate once with your Merge Agent Handler account, and run a single setup command from your project root.

That command writes a ## Merge CLI section to the project's .cursorrules file, which tells Cursor's agent when to call merge search-tools and merge execute-tool to reach GitLab.

Once connected, Merge handles GitLab OAuth credentials and token rotation so you never store a personal access token locally or configure auth state in the project.

Here's the registration command:

merge setup cursor

Prerequisites

Before getting started, you'll need the following:

• A Merge Agent Handler account
• Cursor installed
• pipx installed (run pipx --version to confirm, or install via pip install pipx)
• A GitLab account with access to the projects you want to connect (GitLab.com or self-managed)

If you want to connect Merge Agent Handler's GitLab MCP with internal or customer-facing agentic products, you can follow the steps in our docs.

1. Install the Merge CLI

Run the following to install the Merge CLI and confirm it's available: pipx install merge-api

Verify your installation: merge --versionmerge --version

2. Log in to Merge

Authenticate the CLI with your Merge Agent Handler account: merge login

This links the CLI to your account and authorizes it to make requests to GitLab on your behalf.

Related: How to use a GitLab MCP in Claude Code

3. Connect the CLI to Cursor

Run the following from the root of the project where you want to use Merge tools:

merge setup cursor

This writes a ## Merge CLI section to .cursorrules so Cursor knows to use the CLI for third-party services. The command is idempotent and safe to re-run if you need to reset.

4. Authenticate GitLab

Open a Cursor chat in your project and start with a query that reflects real development work: pulling real issue structures before writing triage or routing logic.

The first time you invoke a GitLab tool, a Magic Link will appear to complete connector authentication.

{{this-blog-only-cta}}

GitLab MCP FAQ

In case you have more questions on setting up and using the GitLab MCP in Cursor, we've addressed several more commonly-asked questions below.

What can you do once the GitLab MCP is connected to Cursor?

With GitLab connected, Cursor can:

• Inspect live issue schemas while writing triage logic: fetch real issue objects including label arrays, milestone references, and assignee structures before coding routing rules, so your logic handles the actual field shape rather than a synthetic fixture

• Pull MR diff content while implementing code review automation: retrieve the diff structure and comment thread data from a real merge request to validate that your parsing and summarization logic handles what GitLab actually returns

• Query CI job logs while writing a failure handler: fetch actual pipeline job output from a failing run to understand the error format your handler needs to parse, classify, and route before writing that logic

• Look up project labels and IDs while coding a labeling automation: retrieve the full label set for a project, including IDs and descriptions, before writing label-assignment code so the identifiers in your logic match the project's actual configuration

• Check commit metadata while building a changelog generator: pull recent commit records with author, timestamp, and message fields to verify the structure your changelog template needs to consume

• Retrieve project members and access levels while implementing permission checks: fetch the full member list with their access tiers before writing authorization logic, so your permission model reflects what GitLab's API actually exposes

Why use Merge Agent Handler vs. a self-hosted GitLab MCP server?

You can run a self-hosted MCP server on top of GitLab's REST API. For a developer working with a single project and a personal access token, the setup is quick. GitLab's API is well-documented, the endpoints cover the same surface, and scoping a token to specific permissions is manageable at the individual level.

The challenge is shared deployment.

GitLab personal access tokens are tied to individual accounts with fixed expiration dates. A self-hosted MCP server backed by a shared service account gives that account's full access level to any agent connected to it, with no per-agent controls on which projects or operations each agent can reach. When the service account's token expires or gets rotated, every agent that depends on it goes down at the same time.

GitLab does publish an official MCP server through GitLab Duo, but it requires an active Duo subscription per user. Teams that aren't already paying for Duo, or that want to expose GitLab data to agents running outside GitLab's own tooling ecosystem, have to provision licenses before they can connect.

Merge Agent Handler handles GitLab authentication centrally without requiring individual tokens per agent or a Duo subscription.

You can define exactly which GitLab operations each agent can call. An agent that monitors merge request review lag, for example, can get merge_requests_list. But it never reaches write operations like repository_delete_file or merge_requests_merge unless those tools are explicitly included.

Every call is logged with the timestamp, tool name, and inputs.

For teams running agents against repositories that contain production code, that level of scoping and logging is the difference between a controlled deployment and an ungoverned one.

Why connect GitLab to Cursor?

GitLab contains the live operational state of a software project: open issues with labels and assignees, merge requests in review with comments and approval status, pipeline results with job-level logs, and the repository itself.

Developers writing code that depends on any of that state, whether for automation, integration, or tooling, need access to real data to write code that works against it.

With the GitLab MCP connected, Cursor can pull that data inline during a coding session.