Skip to content

ADR 0004: Serve MCP 2026-07-28 alongside 2025-11-25 ​

Status: Accepted (2026-07-29)

Context ​

ADR 0002 pinned the hand-written adapter to MCP 2025-11-25. The 2026-07-28 revision, published 2026-07-28, makes the protocol stateless: it removes the initialize/notifications/initialized handshake, protocol-level sessions, and ping; makes server/discover mandatory; and adds a required resultType, cache hints on list results, and mirrored request headers on Streamable HTTP.

Clients will migrate at their own pace, so a server that only spoke the new revision would strand its current hosts, and one that only spoke the old one would fall out of the ecosystem. Both must work at once.

References: changelog, Streamable HTTP.

Decision ​

One dispatcher, two profiles. The revisions share their method semantics (tools/list, tools/call, resources/*, and prompts/* behave identically) and differ only in lifecycle and result-envelope shape. That difference lives behind Knossos\Mcp\Protocol\ProtocolProfile, with Profile20251125 and Profile20260728 implementations and a ProtocolNegotiator that selects one per message: initialize pins a connection to the handshake era, an io.modelcontextprotocol/protocolVersion in _meta selects explicitly, and anything else defaults to the stateless revision.

Profile20251125 output is byte-identical to what the adapter emitted before. That is a constraint, not an aspiration: it is what lets the existing conformance tests stand unedited as a regression net, and what reduces a specification erratum to an edit of one class.

The keepalive is profile-gated. Knossos pings every 25 seconds because hosts close idle stdio transports at 60; 2026-07-28 deletes ping. Rather than send a removed method, the stateless profile simply stops pinging. Measured cold start is 57–73 ms to a database-backed response against a 306 MB graph, so a dropped idle connection costs a reconnect and nothing else. Statelessness is what pays for this, and it is the reason the decision is safe.

Consequences ​

  • Knossos interoperates with both eras through one dispatcher, and the legacy path is isolated rather than entangled.
  • HttpSessionStore and the session branches of HttpEndpoint serve only 2025-11-25 and are scheduled for deletion when that support is dropped: the specification sets a twelve-month minimum deprecation window, so no earlier than 2027-07.
  • Streamable HTTP now validates mirrored Mcp-Method/Mcp-Name/ MCP-Protocol-Version headers against the body, which closes a confused-deputy and gives operators body-free proxy policy. See the threat model.
  • Most of the revision costs nothing here, because Knossos never adopted what it replaces: subscriptions/listen (nothing is subscribable: subscribe: false, listChanged: false), MRTR (the keepalive was the only server-initiated request), and the newly deprecated Roots, Sampling, and Logging features, none of which Knossos uses.
  • x-mcp-header is deliberately not adopted: it is server-optional, and no Knossos tool parameter belongs in a routing header.
  • The tasks extension (io.modelcontextprotocol/tasks) negotiates through server/discover, which this ADR makes available. Adopting it (so a long scan returns a durable handle instead of holding a connection) is separate work.