Skip to content

ADR-0019 — Adopt MCP 2026-07-28 as the sole protocol (clean break)

  • Status: Accepted
  • Date: 2026-06-11

Context

The MCP 2026-07-28 revision (release candidate locked 2026-05-21; final ships 2026-07-28) is not an incremental update — it is a redesign of the protocol's core interaction model. The initialize / notifications/initialized handshake is removed (SEP-2575). Sessions and the Mcp-Session-Id header are removed (SEP-2567); every request is self-contained, carrying its protocol version, client identity, and client capabilities in _meta. Server-initiated requests are replaced by Multi Round-Trip Requests (SEP-2322). Roots, Sampling, and MCP Logging are deprecated (SEP-2577). A mandatory server/discover method replaces handshake-time capability negotiation. See the draft changelog.

Mocapi as shipped through 0.17.0 was built around the previous model: stateful sessions backed by a pluggable store (ADR-0007), a handshake-driven lifecycle validated per message (ADR-0009), and a cross-node Mailbox rendezvous for server-initiated elicitation and sampling (ADR-0008). Supporting both revisions would mean carrying two lifecycles, two dispatch paths, two capability models, and the entire durable-state machinery — for the benefit of clients that, today, do not exist: mocapi has no real current consumers.

The choice is between dual-protocol support (the stateful design lives on as a compatibility mode) and a clean break (the library is rewritten as if it had been designed against 2026-07-28 from the start). The maintainer explicitly chose not to carry the stateful design forward as a boat anchor.

Decision

Mocapi supports exactly one protocol version: "2026-07-28". There is no legacy handshake path and no dual-protocol support.

Rules:

  1. server/discover advertises "2026-07-28" as the only supported version. A request carrying any other io.modelcontextprotocol/protocolVersion is rejected with UnsupportedProtocolVersionError (see ADR-0020).
  2. A legacy client POSTing initialize receives a modern JSON-RPC error, per the spec's backward-compatibility guidance for single-revision servers. Mocapi does not special-case the method.
  3. The rewrite is not a compatibility layer over the old core. Code that exists only to serve the previous revision — sessions, the handshake, the server-initiated request channel — is deleted, not bypassed. The consequent architecture decisions are recorded in ADR-0020, ADR-0021, and ADR-0022.
  4. The release candidate is the build target; the final 2026-07-28 publication is re-verified against the shipped code before release.

Consequences

What this buys us. One protocol version means one lifecycle, one dispatch path, one capability model, and no version-conditional branches anywhere in the core. The framework's architecture matches the spec's architecture, so every spec concept maps to exactly one mocapi concept. The stateless model dramatically simplifies multi-node deployment (see ADR-0020).

Costs. Clients speaking 2025-11-25 or earlier cannot talk to a mocapi server at all — they get a JSON-RPC error, not a downgrade. That is acceptable precisely because no real consumers exist today; if mocapi had a production install base this decision would have gone the other way. Pre-1.0 semantics apply: this is a breaking minor release.

Non-goals. No version negotiation, no "compat mode" flag, no transitional release that supports both revisions. If a future MCP revision lands, the same question gets asked again on its own merits — this ADR does not commit mocapi to single-version support forever, only to not carrying the 2025-11-25 stateful design.

Code anchors: mocapi-server/src/main/java/com/callibrity/mocapi/server/McpServer.java, mocapi-server/src/main/java/com/callibrity/mocapi/server/DefaultMcpServer.java.