## Why Follow-up from #611372 and !253324. MCP spec revision [`2026-07-28`](https://modelcontextprotocol.io/specification/2026-07-28/changelog) replaces the stateful protocol with a stateless one: - Drops the `initialize` handshake, `Mcp-Session-Id`, the GET stream, and SSE resumability. - Every request carries [`_meta`](https://modelcontextprotocol.io/specification/2026-07-28/basic/index) with a protocol version and client capabilities. - Servers expose a new [`server/discover`](https://modelcontextprotocol.io/specification/2026-07-28/server/discover) method. - Results carry a `resultType`. Our server is already stateless, so the gap is small. !253324 made us stop claiming `2026-07-28`, so an `initialize` asking for it gets `2025-11-25` back. That is correct, but it leaves us speaking only the legacy protocol. This issue adds the stateless revision alongside the legacy one, on the same endpoints. Extensions are negotiated the same way, through `clientCapabilities.extensions` in `_meta` and `capabilities.extensions` in `server/discover`. So the tasks, elicitation, skills and apps work is blocked on this issue. ## Where we are today ### What we have - A stateless server in practice: we never mint or read `Mcp-Session-Id`, handle each POST independently, return 405 on GET, and never push to clients. - `initialize` as a pure function that echoes back a version and capabilities, in [`lib/api/mcp/handlers/initialize_request.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/mcp/handlers/initialize_request.rb) and its EE twin [`ee/lib/api/orbit/mcp_handlers/initialize_request.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/api/orbit/mcp_handlers/initialize_request.rb). - Two endpoints with duplicated JSON-RPC handling, [`lib/api/mcp/base.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/mcp/base.rb) and [`ee/lib/api/orbit/mcp.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/api/orbit/mcp.rb). Reviewers asked for a shared helper on !253324 and !253329. - A start on that helper. !253329 added [`lib/api/helpers/mcp/json_rpc.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/helpers/mcp/json_rpc.rb), which holds only `jsonrpc_request_id` today. - A third response writer. `QueryRunner::McpRenderer#envelope` and `stream_frame` in [`ee/lib/analytics/knowledge_graph/query_runner.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/analytics/knowledge_graph/query_runner.rb) build the JSON-RPC envelope for Orbit command results, on both endpoints. - A `tools/list` that varies per caller, so its `cacheScope` must be `"private"`. It depends on: - the current user: `tool.available?`, plus EE governance (`governed_tool_data`), which drops tools under a Deny rule and marks tools under an Ask rule in `_meta` - the token: `ai_workflows` lets the Duo Workflow token list unlisted tools by name. A token needs `mcp` or the granular scope to reach the endpoint at all, so that scope controls access but doesn't change the list. - the `X-Gitlab-Enabled-Mcp-Server-Tools`, `X-Gitlab-Enabled-Mcp-Server-Toolsets` and `X-Gitlab-Mcp-Server-Tool-Name-Prefix` headers - for the `orbit` toolset, the Orbit command catalog for the request - `-32002` with HTTP 403 for a governance Deny. This revision says implementations must not emit `-32002`. #638181 replaces it with a tool error for every protocol version. - Docs for the supported versions. !253836 added the supported version table and the deprecation policy to [`doc/user/model_context_protocol/mcp_server.md`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/model_context_protocol/mcp_server.md), and the table links this issue. ### What we do not have - `server/discover`. A request for it returns HTTP 404 with `-32601`. The spec makes this method mandatory. - Reading `_meta` keys other than `io.modelcontextprotocol/clientInfo`, which `Gitlab::Mcp::ClientInfo` already reads. - Validation of the `MCP-Protocol-Version`, `Mcp-Method`, and `Mcp-Name` headers. - `resultType`, `io.modelcontextprotocol/serverInfo`, `ttlMs`, or `cacheScope` in results. Note the full `_meta` key name, it is not a bare `serverInfo`. - `-32020` and `-32022`. The third code this revision defines, `-32021`, has no use until a request needs a client capability. #634616 adds it for elicitation. <details><summary>What the earlier version of this issue got wrong</summary> - It said we have `-32001` for version mismatch and that it "stays correct for legacy requests". Neither part holds. The entry sits in `lib/api/mcp/base.rb` and nothing references it, in `lib/`, `ee/lib/`, `spec/`, or `ee/spec/`. An unsupported version raises `ArgumentError`, which the endpoint turns into `-32602`. The spec also now treats `-32000` to `-32019` as legacy and tells new implementations not to use it. So `-32001` is dead code to delete, not behaviour to keep. - It listed only `-32020` and `-32022`. The revision defines three codes. `-32021` `MissingRequiredClientCapability` was missing. - It wrote `_meta.serverInfo`. The real key is `io.modelcontextprotocol/serverInfo`. - It said header validation returns `-32020` "on a mismatch". A missing required header is also a `-32020`. It also left out the `=?base64?VALUE?=` sentinel on `Mcp-Name`, which the server must decode before it compares the value to the body. That comparison is the whole point of the header rules, so skipping the decode would let a caller put one name in the header and another in the body. - It listed the shared helper and the docs update as new work. !253329 and !253836 already start both. </details> ## Proposed approach **Phase 1: dual-era server (this issue)** The child tasks hold the work. Once they land, change `mcp_server_stateless_protocol` from `wip` to `beta` and open its rollout issue from the [Feature Flag Roll Out template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20Flag%20Roll%20Out.md). That step belongs to this issue, not to a task. **Phase 2: #638415** `subscriptions/listen`. ## Constraints - One feature flag, `mcp_server_stateless_protocol`, with actor `current_user`. #628250 adds it as type `wip`. It gates `server/discover` (#628252), modern request detection with `-32022` and `-32602` (#628250), header validation (#628251), and the result fields (#628253). #628249 and #638181 don't need it. - With the flag off, every request is legacy, no `-32022` is sent, and `server/discover` answers 404 with `-32601` as today, so clients fall back to `initialize`. - The flag is per user, so `server/discover` uses `cacheScope: "private"`. - While the flag is on, every result carries `resultType: "complete"` and `io.modelcontextprotocol/serverInfo`, whatever its protocol version. ## Open questions - ~~Which protocol version do the Duo Agent Platform executor and Duo Chat clients send today, and will they move to `langchain.mcp` or the FastMCP client? This decides how urgent phase 1 is.~~ Answered: DAP connects to this server through Workhorse's go-sdk v1.6.1 client, which sends `initialize` with 2025-11-25. DWS has no MCP client of its own. The IDE client, the GitLab Language Server on TS SDK 1.32.2, also sends 2025-11-25. Neither moves to 2026-07-28 until its SDK is bumped. For DAP, that's the go-sdk bump in #638180. - ~~How does a dual-era client react to our current 404 `-32601` for `server/discover`? The spec lists `-32601` as a recognized modern error, so a client could read us as a modern server with no discovery support. We should test this with the LangChain client before and after the change.~~ Answered: servers must implement `server/discover`, so this only applies while the flag is off. go-sdk after v1.6.1 falls back to `initialize` on our 404 (#638180). There's no LangChain client to test with. #628252 tests it with the go-sdk version Workhorse moves to. - ~~The transport revision also says a server must validate the `Origin` header and answer 403 when it is present and invalid. We should check whether Workhorse or Rails already covers this for API endpoints before we add anything.~~ Answered: nothing checks `Origin` on the MCP endpoints. The spec's reason for the rule is DNS rebinding against servers with no auth. Ours requires a token (a session cookie fails the scope check), and the API's CORS policy already allows any origin without credentials, so we treat every `Origin` as valid. 2025-11-25 has the same rule, so this isn't new in this revision. - ~~This revision says a request `id` must not be null and a notification must not carry one. Our Grape params mark `id` optional on both endpoints. Worth deciding whether to tighten that for modern requests.~~ Answered: a null `id` already fails validation with `-32600` on both endpoints, for every protocol version. A request without an `id` is #638380. - ~~No urgency signal yet: `@jessieay` tested on !253324 that Cursor 3.15 and 3.19 still ask for `2025-11-25`. No popular client needs this today. This is about being ready, not fixing a break.~~ Answered in the Why section: the tasks, elicitation, skills and apps extensions are blocked on this issue. ## References - [Changelog](https://modelcontextprotocol.io/specification/2026-07-28/changelog) - [SEP-2575](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575): stateless protocol, `_meta`, `server/discover` - [SEP-2567](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2567): sessions removed - [SEP-2243](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2243): `Mcp-Method` and `Mcp-Name` headers - [SEP-2549](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2549): `ttlMs` and `cacheScope` - [SEP-2322](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2322): `resultType` - [Error codes](https://modelcontextprotocol.io/specification/2026-07-28/basic/index#error-codes): `-32020`, `-32021`, `-32022` - [Versioning and backward compatibility](https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning) - [Streamable HTTP](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http) - [`server/discover`](https://modelcontextprotocol.io/specification/2026-07-28/server/discover) - [Base protocol and `_meta`](https://modelcontextprotocol.io/specification/2026-07-28/basic/index) - [Caching](https://modelcontextprotocol.io/specification/2026-07-28/server/utilities/caching) - [LangChain: MCP in LangChain, stateless protocol, elicitation, and more](https://www.langchain.com/blog/mcp-in-langchain-stateless-protocol-elicitation-and-more)