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::InitializeRequest gets a private server_instructions hook that returns nil. The result hash is .compacted, so CE responses are unchanged.
  • EE::API::Mcp::Handlers::InitializeRequest overrides it to return DAP_FLOW_INSTRUCTIONS (512 characters) when Mcp::Tools::DuoWorkflows::Availability#available? is true. That is the same check that lists the duo_agent_platform tools, so the instructions appear exactly when the tools they point to do. The check is memoized per request, so calling the hook from both invoke and log_initialize costs nothing extra.
  • The initialize line in mcp.log gets server_instructions_sent (true or false). The initialize_mcp_connection internal event is unchanged.
  • No feature flag, as agreed in the issue.
  • Known gap, documented: initialize can't see the X-Gitlab-Enabled-Mcp-Server-Toolsets header, so a client that leaves out duo_agent_platform still gets the text.
  • Docs: the note sits in the duo_agent_platform part of the toolsets section of mcp_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.

  1. Call initialize as a user who can use GitLab Duo Agent Platform. On my GDK that's root. 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.instructions is present and identical to the text in #634949 (512 characters). The same call against GDK on master returns no instructions.

  2. Repeat as a user who can't use GitLab Duo Agent Platform, for example a user in an organization with it turned off (namespace1 in common-org on my GDK). instructions is absent.

  3. Check the initialize lines in log/mcp.log:

    {"event_name":"initialize","gl_user_id":1,...,"server_instructions_sent":true}
    {"event_name":"initialize","gl_user_id":459,...,"server_instructions_sent":false}
  4. tools/list for the same two users: root gets the five duo_agent_platform tools, namespace1 gets none. So the instructions arrive exactly when list_duo_agents_and_flows is 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, both base_spec.rb files, ee/spec/services/mcp/tools/duo_workflows/availability_spec.rb and ee/spec/requests/api/orbit/mcp_spec.rb: 220 examples, 0 failures.
  • CE (FOSS_ONLY=1): the CE request spec, unit spec and base_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 from Availability, 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 adds server_instructions_sent: false there.
  • 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.

Edited by Fred de Gier

Merge request reports

Loading
Loading