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). Thedatalists the supported versions and the requested one. - A request for the stateless revision without
io.modelcontextprotocol/clientCapabilitiesreturns HTTP 400 with-32602(Invalid params). An empty{}counts as present. - A request with no
_meta, a_metathat is not a Hash,paramsthat is an Array, or a handshake version is a legacy request. Nothing changes for it. initializeand notifications skip the new check. 2026-07-28 requires these_metakeys only on requests, andinitializemust 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
- Closes #628250 (closed)
- Parent: #627825
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).
- 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"; } - Modern client, both keys. Expect
HTTP 200and"id":1:mcp '{"jsonrpc":"2.0","id":1,"method":"ping","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}' - Modern client without capabilities. Expect
HTTP 400and"code":-32602:mcp '{"jsonrpc":"2.0","id":2,"method":"ping","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}' - Unknown version. Expect
HTTP 400,"code":-32022,data.requested"2099-01-01", anddata.supportedlisting2026-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":{}}}}' - Legacy clients are unchanged. Each one expects
HTTP 200:The last one returnsmcp '{"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"}}'"protocolVersion":"2025-06-18"inresult. - 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"}}}' - 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.