Validate the per-request _meta on both MCP endpoints

What does this MR do and why?

MCP revision 2026-07-28 drops the initialize handshake. Every request now carries the protocol version and the client capabilities in params._meta.

This MR reads and validates that _meta on both MCP endpoints (/mcp and /orbit/mcp):

  • An unknown protocol version returns HTTP 400 with JSON-RPC error -32022 (Unsupported protocol version). The data lists the supported versions and the requested one.
  • A request for the stateless revision without io.modelcontextprotocol/clientCapabilities returns HTTP 400 with -32602 (Invalid params). An empty {} counts as present.
  • A request with no _meta, a _meta that is not a Hash, params that is an Array, or a handshake version is a legacy request. Nothing changes for it.
  • initialize and notifications skip the new check. 2026-07-28 requires these _meta keys only on requests, and initialize must behave exactly as before.

The check lives in validate_jsonrpc_request_meta! in the shared API::Helpers::Mcp::JsonRpc helper. The new API::Helpers::Mcp::RequestMeta value object parses _meta and reuses the version lists from InitializeRequest.

It is behind the wip feature flag mcp_server_stateless_protocol, which is off by default. With the flag off, every request is treated as legacy. Because of the flag, there is no changelog entry.

Specs were not run locally. CI runs them.

References

Screenshots or screen recordings

Not applicable. This is a backend-only change.

Before After

How to set up and validate locally

Runs on a GDK at http://gdk.test:3000, repo at ~/gdk/gitlab. MCP needs a token with the mcp scope (an api token gets 403).

  1. Enable the MCP server and the flag, and create a token:
    cd ~/gdk/gitlab
    bin/rails runner 'Gitlab::CurrentSettings.update!(mcp_server_enabled: true); Feature.enable(:mcp_server_stateless_protocol); puts User.find_by_username("root").personal_access_tokens.create!(name: "mcp-628250", scopes: [:mcp], expires_at: 7.days.from_now).token'
    export TOKEN=<token printed above>
    mcp() { curl -s -w '\nHTTP %{http_code}\n' -X POST http://gdk.test:3000/api/v4/mcp -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d "$1"; }
  2. Modern client, both keys. Expect HTTP 200 and "id":1:
    mcp '{"jsonrpc":"2.0","id":1,"method":"ping","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'
  3. Modern client without capabilities. Expect HTTP 400 and "code":-32602:
    mcp '{"jsonrpc":"2.0","id":2,"method":"ping","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}'
  4. Unknown version. Expect HTTP 400, "code":-32022, data.requested "2099-01-01", and data.supported listing 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26:
    mcp '{"jsonrpc":"2.0","id":3,"method":"ping","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2099-01-01","io.modelcontextprotocol/clientCapabilities":{}}}}'
  5. Legacy clients are unchanged. Each one expects HTTP 200:
    mcp '{"jsonrpc":"2.0","id":4,"method":"ping"}'
    mcp '{"jsonrpc":"2.0","id":5,"method":"ping","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2025-06-18"}}}'
    mcp '{"jsonrpc":"2.0","id":6,"method":"ping","params":{"_meta":"not-a-hash"}}'
    mcp '{"jsonrpc":"2.0","id":7,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}'
    The last one returns "protocolVersion":"2025-06-18" in result.
  6. Flag off: the unknown version is now legacy. Expect HTTP 200:
    bin/rails runner 'Feature.disable(:mcp_server_stateless_protocol)'
    mcp '{"jsonrpc":"2.0","id":8,"method":"ping","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2099-01-01"}}}'
  7. Optional, only if Orbit is enabled locally: repeat steps 2 to 4 against http://gdk.test:3000/api/v4/orbit/mcp. The results are the same.

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 Duo Developer

Merge request reports

Loading
Loading