Merge Unified's GitLab integration Merge Agent Handler's GitLab MCP server

Connect your AI Agents to GitLab in minutes

Merge lets you securely connect your agents to GitLab and thousands of tools instantly

Start building for free

Read docs

GitLab

Learn more about Merge Agent Handler

Available tools

list_branches

List all branches in a project repository with optional search filtering and pagination support for navigating branch lists in large repositories

get_branch

Get detailed information about a specific branch by project ID and branch name, including commit details, merge status, protection status, and access permissions

create_branch

Create a new branch from a specified source branch, tag, or commit SHA with branch name and ref, enabling parallel development workflows and feature branching

delete_branch

Delete a branch from a project repository permanently, removing the branch reference but preserving commits in the repository history if they are referenced elsewhere

protect_branch

Protect a branch with push and merge access level restrictions, allowed users/groups, code owner approval requirements, and unprotect access control for enforcing branch protection policies

unprotect_branch

Remove protection from a branch to allow unrestricted access, disabling all branch protection rules and access level restrictions

list_commits

List all commits in a project repository with comprehensive filtering by ref, date range, path, author, and more, plus pagination support for exploring repository history

get_commit

Get detailed information about a specific commit by project ID and commit SHA, including message, author, committer, timestamps, parent commits, stats, and complete commit metadata

create_commit

Create a commit with multiple file operations in one atomic commit. Each actions item is an object: {action: 'create'|'update'|'delete'|'chmod'|'move', filepath, content (create/update), encoding ('text'|'base64'), previouspath (move), executefilemode (chmod)}. Use startbranch to branch off before committing.

get_commit_diff

Get the diff of changes introduced by a specific commit, showing file modifications, additions, deletions, and detailed line-by-line changes

list_commit_comments

List all comments on a specific commit showing discussions, code review feedback, and inline comments with author, timestamps, and comment content

create_commit_comment

Create a new comment on a commit with optional inline file and line reference for code review, feedback, and commit discussions

get_file

Get a file from a repository with base64-encoded content, metadata, blob ID, commit ID, size, encoding, and last commit information for file inspection and content retrieval

get_raw_file

Get the raw content of a file from a repository (plain text or binary) without base64 encoding for direct content access and display

create_file

Create a new file in a repository with specified content, commit message, branch, and encoding for adding files programmatically

update_file

Update an existing file in a repository with new content, commit message, and optional last commit ID verification for file modification

delete_file

Delete a file from a repository with specified commit message, branch, and optional last commit ID verification for file removal

list_groups

List all accessible groups in GitLab with comprehensive filtering by search query, owned groups, top-level groups, visibility, and more, plus pagination support for large group directories

get_group

Get detailed information about a specific group by ID or path, including name, description, visibility, avatar, projects, members, statistics, and complete group metadata

create_group

Create a new group or subgroup with specified name, path, visibility, description, and settings for organizing projects and managing access across multiple repositories

update_group

Update an existing group's name, path, description, visibility, settings, and permissions for modifying group configuration and access control

delete_group

Delete a group and all its projects, subgroups, and associated data permanently, asynchronous operation that schedules group deletion (requires owner permissions)

list_issues

List all issues in a GitLab project with comprehensive filtering by state, labels, milestone, assignee, author, search query, and date ranges, plus pagination support for large issue collections

get_issue

Get comprehensive detailed information about a specific GitLab issue by project ID and issue IID including description, state, labels, assignees, time tracking, and linked resources

create_issue

Create a new GitLab issue with title, description, labels, assignees, milestone, due date, and confidentiality settings for comprehensive issue tracking

update_issue

Update an existing GitLab issue's title, description, state, labels, assignees, milestone, or other properties with support for state transitions and label management

delete_issue

Permanently delete a GitLab issue by project ID and issue IID including all its comments, attachments, and metadata (irreversible operation)

move_issue

Move a GitLab issue from one project to another project while preserving history, comments, and metadata, creating a new issue IID in the target project

list_jobs

List all CI/CD jobs in a GitLab project with filtering by scope (created, pending, running, failed, success, canceled, skipped, manual) and pagination support for comprehensive job tracking and monitoring

list_pipeline_jobs

List all CI/CD jobs in a specific pipeline with optional filtering by scope, showing all job stages, statuses, and execution details for pipeline-specific job tracking and debugging

get_job

Get detailed information about a specific CI/CD job by project ID and job ID, including status, stage, name, duration, artifacts, runner, user, commit, and complete execution metadata

cancel_job

Cancel a running or pending CI/CD job immediately, stopping job execution and transitioning it to canceled status, useful for stopping incorrect or unnecessary job runs

retry_job

Retry a failed or canceled CI/CD job, creating a new job instance and rerunning it with the same configuration, useful for handling transient failures and flaky tests

play_job

Trigger a manual CI/CD job to run with optional variables, starting jobs that require manual action and supporting parameterized manual job execution for controlled deployments and operations

erase_job

Erase a CI/CD job's artifacts and trace log permanently, removing build outputs and logs while keeping job metadata and status, useful for removing sensitive data or large artifacts

get_job_trace

Get the log trace output of a CI/CD job showing all console output, script execution, build logs, and job execution details, essential for debugging failed jobs and monitoring job progress

list_labels

List all labels in a project with optional issue and merge request counts, color, description, and pagination support for label management and organization

get_label

Get detailed information about a specific label by project ID and label ID, including name, description, color, priority, and usage statistics

create_label

Create a new label with specified name, color, and optional description and priority for issue and merge request categorization and filtering

update_label

Update an existing label's name, color, description, or priority for modifying label appearance and organization

delete_label

Delete a label from a project permanently, removing the label from all issues and merge requests that use it

list_merge_requests

List all merge requests in a GitLab project with comprehensive filtering by state, labels, assignee, reviewer, source/target branch, draft status, and date ranges, plus pagination support for large MR collections

get_merge_request

Get detailed information about a specific merge request by project ID and MR IID, including description, state, branches, assignees, reviewers, pipeline status, merge status, conflicts, approvals, and time tracking

create_merge_request

Create a new merge request with source branch, target branch, title, description, assignees, reviewers, labels, milestone, and merge settings including squash commits and remove source branch options

update_merge_request

Update an existing merge request's title, description, state, target branch, assignees, reviewers, labels, milestone, squash settings, and other properties including discussion lock and remove source branch options

delete_merge_request

Delete a merge request from a project by project ID and MR IID, permanently removing the merge request and all associated data including comments, approvals, and metadata

merge_merge_request

Accept and merge a merge request with optional custom commit message, squash commits, auto-remove source branch, and merge when pipeline succeeds settings, completing the code review and integration process

approve_merge_request

Approve a merge request to indicate review approval and satisfy approval rules, contributing to the required approvals count before the merge request can be merged

unapprove_merge_request

Remove approval from a merge request, retracting the authenticated user's previous approval and decreasing the approvals count

list_milestones

List all milestones in a project with filtering by state (active, closed, all), title search, and pagination support for milestone management and sprint planning

get_milestone

Get detailed information about a specific milestone by project ID and milestone ID, including title, description, state, dates, progress, and issue/MR counts

create_milestone

Create a new milestone with title, description, and optional due date and start date for sprint planning, release management, and goal tracking

update_milestone

Update an existing milestone's title, description, dates, or state (activate/close) for modifying sprint plans and release schedules

delete_milestone

Delete a milestone from a project permanently, removing the milestone but preserving associated issues and merge requests

list_issue_notes

List all comments/notes on a specific issue with author, timestamps, content, and pagination support for tracking discussions and feedback

get_issue_note

Get detailed information about a specific note/comment on an issue by project ID, issue IID, and note ID

create_issue_note

Create a new comment/note on an issue with Markdown content for adding feedback, discussion, and collaboration

update_issue_note

Update an existing comment/note on an issue to modify content or mark as resolved

delete_issue_note

Delete a comment/note from an issue permanently, removing the comment from the discussion history

list_merge_request_notes

List all comments/notes on a specific merge request with author, timestamps, content, and pagination support for code review and discussion tracking

get_merge_request_note

Get detailed information about a specific note/comment on a merge request by project ID, MR IID, and note ID

create_merge_request_note

Create a new comment/note on a merge request with Markdown content for code review feedback, discussion, and collaboration

update_merge_request_note

Update an existing comment/note on a merge request to modify content or resolve discussions

delete_merge_request_note

Delete a comment/note from a merge request permanently, removing the comment from the code review discussion history

list_pipelines

List all CI/CD pipelines in a GitLab project with comprehensive filtering by scope, status, source, ref, SHA, YAML errors, username, and update dates, plus pagination support for large pipeline collections

get_pipeline

Get detailed information about a specific CI/CD pipeline by project ID and pipeline ID, including status, source, ref, SHA, user, timestamps, duration, coverage, jobs, and detailed status information

create_pipeline

Trigger a new CI/CD pipeline run for a specified branch or tag with optional variables, manually initiating the CI/CD workflow for testing, deployment, or continuous integration

retry_pipeline

Retry all failed jobs in a CI/CD pipeline, rerunning only the jobs that failed while keeping successful jobs unchanged, useful for transient failures and flaky tests

cancel_pipeline

Cancel a running CI/CD pipeline and all its jobs, immediately stopping all running jobs and preventing pending jobs from starting, useful for stopping incorrect or unnecessary pipeline runs

delete_pipeline

Delete a CI/CD pipeline and all its associated data including jobs, artifacts, and logs, permanently removing the pipeline from the project history

list_projects

List all accessible GitLab projects with comprehensive filtering including archived status, visibility level, ownership, membership, and starred projects, plus pagination support for large project collections

get_project

Get comprehensive detailed information about a specific GitLab project by ID or URL-encoded path including repository details, statistics, permissions, and configuration

create_project

Create a new GitLab project with specified name, path, namespace, description, visibility level, and initialization options including automatic README generation

update_project

Update an existing GitLab project's name, path, description, visibility, default branch, topics, and other configuration settings

delete_project

Permanently delete a GitLab project by ID or path including all its data, issues, merge requests, and repository content (irreversible asynchronous operation)

archive_project

Archive a GitLab project to make it read-only and hide it from most project lists while preserving all data and repository access

unarchive_project

Unarchive a previously archived GitLab project to restore it to active status with full read-write access and normal visibility

star_project

Star a GitLab project to add it to your favorites list for quick access and to show appreciation for the project

unstar_project

Unstar a previously starred GitLab project to remove it from your favorites list

fork_project

Create a complete fork of a GitLab project to a specified namespace with optional custom name, path, and description for independent development

add_spent_time

Add time spent working on an issue using human-readable format (e.g., '3h30m', '1h', '2d') for time tracking and project management

get_time_stats

Get time tracking statistics for an issue including time estimate, total time spent, and remaining time in both seconds and human-readable format

set_time_estimate

Set or update the time estimate for an issue using human-readable format (e.g., '3h30m', '2d') for project planning and resource allocation

reset_time_estimate

Reset the time estimate for an issue to zero, removing the estimate while preserving time spent records

reset_spent_time

Reset the spent time for an issue to zero, removing all time tracking records while preserving the time estimate

list_users

List all users in GitLab instance with comprehensive filtering by username, search query, active/blocked status, external users, and more, plus pagination support for large user directories

get_user

Get detailed information about a specific user by user ID, including username, name, email, avatar, state, bio, location, organization, job title, creation date, and complete profile information

get_current_user

Get information about the currently authenticated user including username, name, email, permissions, namespace, private token details, and complete profile information for the API credential in use

create_user

Create a new user account with username, email, password, and optional profile settings, admin-only operation for user provisioning and account management

update_user

Update an existing user's profile, email, username, password, permissions, and settings, supporting admin modifications or self-service profile updates

delete_user

Delete a user account permanently from GitLab, removing the user and optionally hard-deleting all associated data including projects, issues, and contributions (admin only)

validate_credential

Validate GitLab credentials. Verifies credentials during setup.

list_webhooks

List all webhooks configured for a project with URL, token, event triggers, and enable status for webhook management and integration monitoring

get_webhook

Get detailed information about a specific webhook by project ID and hook ID, including URL, event triggers, SSL verification, and configuration

create_webhook

Create a new webhook with URL, secret token, and comprehensive event trigger configuration for push, issues, merge requests, pipelines, deployments, and more

update_webhook

Update an existing webhook's URL, secret token, event triggers, SSL verification, or branch filter for modifying webhook configuration

delete_webhook

Delete a webhook from a project permanently, removing the integration and stopping all event notifications

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's GitLab MCP server

What is a GitLab MCP server?

It’s an MCP server that exposes data and functionality from GitLab via tools. Your agents can use these tools to gather and share commits, upload files to repositories, update issues, and more.

How can I use the GitLab MCP server?

Here are just a few use cases (these also apply to other project management MCP servers):

Code review and merge request assistance: Summarize a merge request’s changes and flag risky diffs

Issue triage and project hygiene: Turn bug reports or Slack threads into GitLab issues with titles, descriptions, labels, and assignees

Release coordination: Build a release checklist by querying the set of MRs/issues targeted for a milestone

CI/CD visibility and debugging: Check pipeline status for a branch or merge request, and pull failed job logs and summarize likely root causes and next debugging steps

Operational workflows: Open incidents or on-call tasks in GitLab when a monitoring alert fires. And keep incident issues updated as deploys roll out and pipelines complete

Security and compliance workflows: Review findings (for example, vulnerabilities) and create tracking issues with owners and due dates

Cross-system automations: Sync work between GitLab and other systems. For example, create a CRM ticket when a security issue is opened, or post updates to a comms channel

What are popular tools for GitLab’s MCP server?

Here are some popular tools across data types.

Issues

<code class="blog_inline-code">list_issues</code>
<code class="blog_inline-code">get_issue</code>
<code class="blog_inline-code">create_issue</code>
<code class="blog_inline-code">update_issue</code>

Jobs

<code class="blog_inline-code">get_job</code>
<code class="blog_inline-code">Retry_job</code>
<code class="blog_inline-code">play_job</code>
<code class="blog_inline-code">erase_job</code>

Projects

<code class="blog_inline-code">star_project</code>
<code class="blog_inline-code">fork_project</code>
<code class="blog_inline-code">create_project</code>
<code class="blog_inline-code">delete_project</code>

What makes Merge Agent Handler’s GitLab MCP server better than alternative GitLab MCP servers?

Merge Agent Handler provides a standardized, enterprise-grade control plane that isn’t available in the official GitLab MCP server. This includes:

Managed authentication and credential handling: Merge provides guided, embeddable authentication flows (Agent Handler Link) and supports both shared and individual authentication per connector, reducing security and UX complexity

Enterprise security with DLP: All tool inputs and outputs pass through a security gateway with configurable Data Loss Prevention rules to block, redact, or mask sensitive data

Real-time observability and auditability: Every GitLab tool call is logged with a fully searchable audit trail, enabling debugging, compliance reviews, and behavioral optimization

Evaluation before production: Tools can be validated against expected outcomes using the Evaluation Suite before being deployed to live agents

Can I set custom security rules for GitLab tool calls in Merge Agent Handler?

Yes. Merge Agent Handler includes a Security Gateway with Data Loss Protection (DLP) that allows you to configure default and custom security rules. These rules inspect GitLab tool inputs and outputs and can block, redact, or mask sensitive data fields based on your organization’s policies.

Here are some examples:

Prevent leaking secrets into GitLab. Block any GitLab write (issue/MR/comment/commit message) that contains API keys, bearer tokens, or credentials

Stop PII from being stored in GitLab. Block tool calls that include SSNs or other sensitive entities in issue descriptions, comments, or fields. Or allow the call but redact the sensitive values based on your policy

Avoid cross-customer data leakage when agents read GitLab. Mask internal identifiers (for example, customer account IDs) in GitLab read results so the agent can’t copy them into another system

Enforce company-specific patterns and policies. Add custom regex-based rules for things like proprietary ID formats, internal ticket numbers, or other sensitive strings that show up in GitLab content

How can I start using Merge Agent Handler’s GitLab MCP server?

You can take these steps:

1. Create a Merge Agent Handler account.

2. Create a Tool Pack for the workflow you want (for example, “GitLab triage”).

3. Add the GitLab connector to that Tool Pack.

4. Configure authentication for GitLab (shared org auth vs individual end-user auth, depending on your setup).

5. Create a Registered User (this represents the identity that will execute tool calls).

6. Complete the GitLab authentication flow for that Registered User so the GitLab tools can execute.

7. Copy the MCP entry URL for your Tool Pack + Registered User and add it to your MCP client (Cursor, Claude Desktop, VSCode, Windsurf, etc.).

8. Use the Playground to run a few GitLab tool calls end-to-end and confirm you see successful responses and logs.

Can employees use Merge Agent Handler to connect their AI tools to GitLab?

Yes, Agent Handler for Employees lets your employees connect Claude, ChatGPT, Microsoft Copilot, Cursor, and other MCP-compatible AI tools to GitLab without bypassing IT governance.

Instead of setting up direct connections with personal credentials that IT can't monitor or revoke, each employee authenticates through Agent Handler and gets individual credentials tied to their identity.

IT also provisions access by role or group via SCIM. An engineer, for example, gets GitLab access to manage code and issues, Datadog to monitor service health, and PagerDuty to respond to alerts; while a PM gets GitLab access to track project progress, Jira to coordinate cross-team tasks, and Slack to stay aligned with stakeholders.

Every tool call an employee's AI makes to GitLab is also inspected against your DLP rules and logged to a searchable audit trail, giving security teams full visibility into what data was accessed and by whom.