> [!note] > This issue adds a new MCP tool. Follow [Adding a new tool](https://docs.gitlab.com/development/duo_agent_platform/mcp/#adding-a-new-tool) guidance, including opening an MCP Tool Proposal, before implementation. ## Problem Statement / Use Case The same customer gap analysis flagged **Merge MR** as a blocking gap: the community `zereight/gitlab-mcp` server ships `merge_merge_request`, the GitLab MCP server has no equivalent. Concrete use case: The customer's SAC team wants an agent that auto-merges a merge request once all required approvals are in — today there is no MCP tool that can merge or set auto-merge on a merge request. ## Proposed Design A standalone GraphQL-backed tool wrapping `Mutations::MergeRequests::Accept` (`mergeRequestAccept`, `app/graphql/mutations/merge_requests/accept.rb`), named after the mutation. **Considered and rejected:** folding merge into `save_merge_request` as a lifecycle action, mirroring the `save_pipeline` precedent (https://gitlab.com/gitlab-org/gitlab/-/work_items/605855). Merge doesn't fit that shape: it's a state transition backed by an entirely separate mutation with its own argument surface (`strategy`, `sha`, `squash`, commit messages, `should_remove_source_branch`) that would bloat `save_merge_request`'s schema. This is therefore an intentional exception to the `get_`/`list_`/`save_`/`delete_` naming taxonomy (https://docs.gitlab.com/development/duo_agent_platform/mcp/#tool-naming-and-consolidation-conventions), following team discussion that treated merge as a state transition rather than a field update. **Intent is explicit through one argument:** no `strategy` means merge now; `strategy` given (the auto-merge trigger condition, e.g. `merge_when_checks_pass`) means set auto-merge, which schedules the merge once the strategy's condition is met. **Why GraphQL and not the REST merge endpoint:** REST `PUT .../merge` takes a boolean `auto_merge` and picks the strategy server-side via `AutoMergeService#preferred_strategy` (`lib/api/merge_requests.rb`). When no strategy condition is currently pending but the merge request is mergeable, the endpoint merges immediately — caller intent "schedule" can silently execute as "merge now". The mutation instead validates strategy eligibility (`merge_request.auto_merge_eligible?(strategy:)`) and returns `NOT_MERGEABLE` when the strategy doesn't apply, rather than silently falling back to an immediate merge. **Guards inherited from the mutation for free:** - Required `sha` argument — errors with `SHA_MISMATCH` when the head has moved (stale-approval / force-push protection). - `ALREADY_SCHEDULED` — setting auto-merge twice errors instead of double-firing. - Pre-merge hooks validation (`HOOKS_VALIDATION_ERROR`). **Branch cleanup** is covered by the mutation's `should_remove_source_branch` argument, not a separate tool. A standalone `delete_branch` tool was considered and rejected: GitHub's MCP server has none either, and the project's `remove_source_branch_after_merge` setting already covers the common case. ## Scope and Non-Goals - In scope: merge now, set auto-merge, `should_remove_source_branch`, `squash`. - Non-goals for v1: - Pre-fetching eligible auto-merge strategies — the mutation's eligibility error is informative enough for an agent to self-correct; a lookup can be added later. - `cancel_auto_merge` — REST `POST .../cancel_merge_when_pipeline_succeeds` already exists; neither stated use case needs cancellation. - Standalone `delete_branch` tool — rejected, see Proposed Design. - Commit message / squash commit message overrides — not required by the stated flows; additive later. ## Resources - Customer gap analysis and internal team discussion. - Mutation: `app/graphql/mutations/merge_requests/accept.rb` (`Mutations::MergeRequests::Accept`, `mergeRequestAccept`) - Auto-merge strategy resolution: `app/services/auto_merge_service.rb` - REST merge endpoint (for contrast): `lib/api/merge_requests.rb` - Precedent GraphQL-backed MCP tools: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/246413 (`list_merge_requests`) and https://gitlab.com/gitlab-org/gitlab/-/merge_requests/249708 (`save_merge_request_review`) - MCP tool naming/consolidation conventions: https://docs.gitlab.com/development/duo_agent_platform/mcp/#tool-naming-and-consolidation-conventions - Companion issue: `approve` method on `save_merge_request_review`, filed alongside this one. ## Implementation Plan 1. Open an MCP Tool Proposal and get the standalone-tool naming exception ratified by the mcp-tool-review-board. 1. Add a `.graphql` mutation document plus `Tool`/`Service` classes under `app/services/mcp/tools/merge_requests/`, following the GraphQL tool pattern (`list_merge_requests` precedent). 1. Input schema: `url` or `project_id` + `merge_request_iid` (shared resource-identification base), `sha` (required), `strategy` (enum, optional), `squash` (optional), `should_remove_source_branch` (optional). 1. Specs (tool + service), including sha-mismatch, already-scheduled, and hooks-validation-failure cases; update BOTH `list_tools` annotation specs (`spec/requests/api/mcp/handlers/list_tools_spec.rb` and `ee/spec/requests/api/mcp/handlers/list_tools_spec.rb`); update `doc/user/model_context_protocol/mcp_server_tools.md`. 1. End-to-end verification via a real MCP client against a running GDK, per the pattern used in https://gitlab.com/gitlab-org/gitlab/-/merge_requests/249708.