Support MCP protocol version 2026-07-28 (v4)

[lloydrichards]

Summary

Add first-class server support for MCP protocol version 2026-07-28 through a new McpProtocol.v2026_07_28 adapter.

Unlike v2025-11-25, this is a new protocol era rather than an incremental schema revision. It replaces the initialization/session lifecycle with stateless, per-request negotiation and changes how discovery, reverse interaction, notifications, and Streamable HTTP routing work.

The existing adapters must retain their current session-based behavior.

Protocol changes

Stateless requests

2026-07-28 removes:

• initialize and notifications/initialized
• protocol-managed sessions
• Mcp-Session-Id

Each request instead carries its protocol version, client capabilities, and optional client identity in _meta. The selected adapter must therefore be resolved from the raw request before its dated payload is decoded.

Streamable HTTP also mirrors routing information through headers such as MCP-Protocol-Version, Mcp-Method, and Mcp-Name. Header/body mismatches return HTTP 400 with MCP error -32020.

Discovery and results

Servers must implement server/discover, advertising:

• supported protocol versions
• server capabilities
• optional instructions
• cache metadata

Every successful modern result includes a resultType. Completed results use "complete"; operations requiring client input return "input_required" with keyed input requests and optional opaque requestState.

Server identity is carried in result _meta.

Multi-round-trip requests

General server-to-client JSON-RPC requests are removed. Elicitation, sampling, and roots interaction now use an InputRequiredResult. The client fulfils those requests and retries the original operation with inputResponses and the byte-exact requestState.

This requires a canonical result boundary that can represent either:

• a completed tool, resource, or prompt result; or
• an input-required result.

The dated adapter owns the corresponding wire projection. Direct McpReverseClient operations must report that they are unsupported for modern requests.

Subscriptions

Unsolicited list-change and resource-update notifications are replaced by subscriptions/listen.

Modern notifications must only be sent through an active subscription and must include the corresponding subscription identifier. Legacy adapters retain their existing session-oriented notification behavior.

Schema differences

The new dated schema must cover:

• required request metadata and result discrimination
• server/discover
• multi-round-trip request and result types
• subscriptions/listen
• cache metadata
• modern errors -32020, -32021, and -32022
• full JSON Schema 2020-12 tool schemas
• unrestricted tool output schemas and structured content
• -32602 for missing resources

Required architecture changes

The existing ProtocolAdapter boundary already owns dated RPC groups, codecs, projections, error mapping, and cancellation normalization. The surrounding runtime still assumes every client has completed initialization and owns a session.

Introduce an adapter-owned lifecycle strategy supporting:

• legacy initialize-and-pin selection;
• modern per-request selection;
• request metadata and HTTP header validation;
• session requirements;
• request-scoped client context;
• result-envelope projection;
• transport-specific cancellation; and
• subscription delivery.

Modern requests must not synthesize an initialization payload or consult the legacy session maps.

flowchart TD
  A["Incoming request"] --> B["Inspect raw envelope"]
  B --> C{"Protocol era"}

  C -->|"initialize"| D["Select legacy adapter"]
  D --> E["Decode initialize"]
  E --> F["Create and pin session"]
  F --> G["Decode later requests with pinned adapter"]

  C -->|"version in request _meta"| H["Select 2026-07-28 adapter"]
  H --> I["Validate body and HTTP headers"]
  I --> J["Create request-scoped profile"]

  G --> K["Invoke McpCore"]
  J --> K

  K --> L{"Canonical result"}
  L -->|"Complete"| M["Encode resultType: complete"]
  L -->|"Needs input"| N["Encode resultType: input_required"]
  N --> O["Client retries with responses and requestState"]
  O --> A

Loading

McpCore should continue owning version-neutral registrations and semantic operations. It should not own dated metadata keys, HTTP headers, resultType, or protocol error numbers.

Acceptance criteria

Protocol adapter

• Add mcpSchema/v2026_07_28.ts and mcpProtocol/v2026_07_28.ts.
• Export McpProtocol.v2026_07_28.
• Update ProtocolAdapter, ProtocolVersion, typetests, and Changesets.
• Implement the final v2026-07-28 RPC vocabulary and wire schemas.

Routing and lifecycle

• Select modern requests from raw per-request metadata before payload decoding.
• Preserve initialize-and-session selection for legacy adapters.
• Serve modern requests without initialization or Mcp-Session-Id.
• Derive capabilities and optional client identity independently for each modern request.
• Support legacy and modern clients on the same configured endpoint.
• Return -32022 with requested and supported versions for unsupported revisions.

Discovery and wire behavior

• Implement server/discover.
• Add required request metadata and successful-result discrimination.
• Stamp modern results with server identity metadata.
• Validate modern HTTP routing headers and return HTTP 400 with -32020 on mismatch.
• Do not create or require modern protocol sessions.
• Preserve existing legacy HTTP behavior.

Multi-round-trip requests

• Add a canonical input-required outcome.
• Support elicitation, sampling, and roots input requests.
• Re-enter operations with keyed inputResponses.
• Round-trip opaque requestState byte-for-byte.
• Reject direct reverse-client operations for modern requests.

Subscriptions

• Implement subscriptions/listen.
• Deliver modern change notifications only through active subscriptions.
• Include subscription identifiers on delivered notifications.
• Preserve legacy notification and resource-subscription behavior.

Schema and conformance

• Support the final JSON Schema 2020-12 tool schema rules.
• Preserve arbitrary JSON structured content.
• Map missing resources to -32602.
• Add a v2026_07_28.test.ts conformance entrypoint.
• Cover discovery, stateless routing, headers, result discrimination, MRTR, subscriptions, and modern errors.
• Add mixed-era tests with v2025_11_25 and v2026_07_28.
• Verify malformed modern requests cannot fall through to a legacy adapter.

Out of scope

• Tasks extension runtime and persistence
• MCP Apps
• client-side MRTR fulfilment
• distributed subscription infrastructure
• removal of legacy sessions
• removal of deprecated roots, sampling, or logging APIs

Tasks and MCP Apps should remain separately composable extensions.

Related work

• Multi-protocol McpServer for supporting upcoming 2026-07-28 spec #6617
• feat: add MCP protocol adapters #6625
• fix: mcp conformance and add test suite #6693
• Support MCP protocol version 2025-11-25 (v4) #6706
• feat: add mcp core for protocol versions #6829
• add first-class support for tasks extension #6834

[lloydrichards]

Some thoughts on the transport runtime:

interface RuntimeDescriptor {
  readonly _tag: "Sessionful" | "Stateless"
  readonly transport: TransportPolicy

  readonly make: (
    context: RuntimeContext
  ) => Effect.Effect<RuntimeInstance>
}

const legacyProtocol = McpProtocol.make({
  protocolVersion: "2025-06-18",
  runtime: McpProtocol.sessionful({
    jsonRpc: {
      acceptsBatches: false
    },
    http: {
      requiresVersionHeader: true
    }
  }),
  // dated RPC groups and projections
})

const modernProtocol = McpProtocol.make({
  protocolVersion: "2026-07-28",
  runtime: McpProtocol.stateless({
    jsonRpc: {
      acceptsBatches: false
    },
    http: {
      validateRoutingHeaders: true
    }
  }),
  // dated RPC groups and projections
})

In this way there is clear seperation between each part, while the adaptor still owns it all.

flowchart TB

A(HTTP / stdio binding)
B(Runtime Router)
C([Sessionful runtime instance])
D(Selected dated adapter)
E[McpCore]
F(Selected dated adapter)
G([Stateless runtime instance])

B --> G
A --> B --> C --> D --> E --> F --> G
G --> F --> E --> D --> C
C --> A
G --> A

Loading

The physical binding carries bytes; the runtime owns lifecycle; the adapter owns the dated wire contract; McpCore owns semantics.