Add server instructions to the MCP initialize response
What does this MR do and why?
The GitLab MCP server now sends server instructions in its initialize response when the user
can use GitLab Duo Agent Platform. They tell external agents to propose a matching GitLab Duo
flow, such as Code Review, and to ask the user before starting it. The text is the one
validated in &24115. Resolves #634949.
How it works
- CE
API::Mcp::Handlers::InitializeRequestgets a privateserver_instructionshook that returnsnil. The result hash is.compacted, so CE responses are unchanged. EE::API::Mcp::Handlers::InitializeRequestoverrides it to returnDAP_FLOW_INSTRUCTIONS(512 characters) whenMcp::Tools::DuoWorkflows::Availability#available?is true. That is the same check that lists theduo_agent_platformtools, so the instructions appear exactly when the tools they point to do. The check is memoized per request, so calling the hook from bothinvokeandlog_initializecosts nothing extra.- The
initializeline inmcp.loggetsserver_instructions_sent(true or false). Theinitialize_mcp_connectioninternal event is unchanged. - No feature flag, as agreed in the issue.
- Known gap, documented:
initializecan't see theX-Gitlab-Enabled-Mcp-Server-Toolsetsheader, so a client that leaves outduo_agent_platformstill gets the text. - Docs: the note sits in the
duo_agent_platformpart of the toolsets section ofmcp_server.md, next to the availability conditions it shares, with a history entry. - #633055 (closed) and
server/discover(#628252) can extend the same hook later. Some clients truncate instructions at 2,048 characters, and a spec guards that limit.
References
- Resolves #634949
- Eval: &24115
Screenshots or screen recordings
No UI change. What a connected client receives from initialize:
| Before | After |
|---|---|
No instructions key |
"instructions": "When a GitLab task matches a GitLab Duo flow, for example reviewing a merge request with code_review/v1, ... Propose it to the user and confirm before starting, unless the user already asked for it." |
How to set up and validate locally
Run on 2026-11-05 against GDK's development database, with the branch served by a second Puma
(bin/rails server -e development -p 3988). Both users have a personal access token with the
mcp scope.
-
Call
initializeas a user who can use GitLab Duo Agent Platform. On my GDK that'sroot. A GDK without a GitLab Duo seat or GitLab credits for the user has none, so only the specs cover this case there.curl -s -X POST "$GDK/api/v4/mcp" \ -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"protocolVersion":"2025-11-25"}}'result.instructionsis present and identical to the text in #634949 (512 characters). The same call against GDK onmasterreturns noinstructions. -
Repeat as a user who can't use GitLab Duo Agent Platform, for example a user in an organization with it turned off (
namespace1incommon-orgon my GDK).instructionsis absent. -
Check the
initializelines inlog/mcp.log:{"event_name":"initialize","gl_user_id":1,...,"server_instructions_sent":true} {"event_name":"initialize","gl_user_id":459,...,"server_instructions_sent":false} -
tools/listfor the same two users:rootgets the fiveduo_agent_platformtools,namespace1gets none. So the instructions arrive exactly whenlist_duo_agents_and_flowsis there to follow them.
Specs and checks
- EE:
spec/requests/api/mcp/handlers/initialize_request_spec.rb,ee/spec/requests/api/mcp/handlers/initialize_request_spec.rb,spec/lib/api/mcp/handlers/initialize_request_spec.rb, bothbase_spec.rbfiles,ee/spec/services/mcp/tools/duo_workflows/availability_spec.rbandee/spec/requests/api/orbit/mcp_spec.rb: 220 examples, 0 failures. - CE (
FOSS_ONLY=1): the CE request spec, unit spec andbase_spec.rb: 80 examples, 0 failures. - With
return super unless available?(current_user)removed, the three EE cases without instructions fail. With the license or credits condition removed fromAvailability, the license case fails too (Alex's suggestion, so it no longer passes because of a missing seat). - The first commit's version of the unit spec fails
logs the initialize request, because it pinned the log fields. The second commit addsserver_instructions_sent: falsethere. - RuboCop, Vale and markdownlint: no new offenses.
MR acceptance checklist
Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.