gitlab-mcp

gitlab_mr_merge

Merge an open GitLab merge request, with an optional source-branch SHA pin so the merge is rejected if newer commits moved the branch.

Instructions

Merge a merge request. The merge request must be opened - merging a merged or closed one fails. It fails with 405 while it is not mergeable (conflicts, or a required pipeline still running) and with 409 when the source branch moved since you read it, so read the merge request first and pass its sha to pin the merge.

Input Schema

TableJSON Schema

Name	Required	Description
`iid`	Yes	project-scoped internal id - the number in !123 for a merge request or #123 for an issue, not the global id
`sha`	No	source-branch HEAD as you read it; a mismatch is rejected rather than merging newer commits
`project`	Yes	project id ('42') or full path ('group/subgroup/app'); a path is URL-encoded for you
`merge_commit_message`	No
`should_remove_source_branch`	No
`merge_when_pipeline_succeeds`	No	schedule the merge instead of merging now

Output Schema

TableJSON Schema

Name	Required	Description
`id`	No
`iid`	No	internal id - the number in !123
`sha`	No	HEAD of the source branch
`state`	No	opened / closed / locked / merged
`title`	No
`author`	No	user reference
`labels`	No
`web_url`	No
`assignee`	No	user reference
`milestone`	No
`project_id`	No
`description`	No
`merge_status`	No	'can_be_merged' / 'cannot_be_merged' / 'unchecked'. A merged merge request on 11.3 still reports can_be_merged, so read state first - merge_status alone is not a green light
`changes_count`	No	a string on 11.3, not a number
`has_conflicts`	No	not sent by 11.3; compare merge_status instead
`source_branch`	No
`target_branch`	No
`merge_commit_sha`	No
`user_notes_count`	No
`work_in_progress`	No	11.3 marks a draft MR this way; the title carries a "WIP: " prefix. Verified present on every one of 100 merge requests on the live instance

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Oct 5, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only supply readOnlyHint=false, so the description carries the behavioral burden and does so richly: precondition (must be opened), failure semantics (405 when not mergeable due to conflicts or a running pipeline; 409 when the source branch moved since read), and the mitigation (read first, pass sha). This is exactly the beyond-annotation context an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action and then the failure modes and remedy. Dense but every clause earns its place; nothing is redundant with the name or schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with an output schema (so return values need not be explained), it covers preconditions, error modes, and the sha-pinning workflow well. Minor gaps remain around permissions and the purpose of merge_commit_message / should_remove_source_branch.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%, above the midpoint baseline. The description adds real meaning to the sha parameter (pinning the merge, mismatch rejected into 409) beyond the schema text. However, merge_commit_message and should_remove_source_branch remain undocumented in both schema and description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Merge a merge request') that is unambiguous and clearly distinct from sibling mutators like gitlab_mr_update, gitlab_mr_create, or gitlab_mr_resolve. An agent can identify the operation without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives strong operational context: the MR must be opened, and it prescribes a workflow ('read the merge request first and pass its sha to pin the merge'). That implicitly points at gitlab_mr_get as a prerequisite, though it never explicitly names an alternative tool or contrasts merging with creating/updating.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.