Part of #4725

Spec links:

• https://modelcontextprotocol.io/specification/draft/server/tools
• https://modelcontextprotocol.io/specification/draft/basic/versioning
• https://modelcontextprotocol.io/specification/draft/changelog

Comprised of: the tools/list portions of the stateless core (#5679, #5680), notification rework (#5681), cache semantics (#5685), required request headers (#5687), and JSON Schema 2020-12 support (#5688), together with the existing dataplane pagination and list-change gaps (#4664, #5346).

What the spec says

• A modern tools/list request is stateless and does not depend on initialize, notifications/initialized, or Mcp-Session-Id.
• Every request carries the negotiated protocol version, client identity, and client capabilities in _meta; Streamable HTTP requests also carry the required MCP headers.
• Servers that advertise the tools capability must return the tools visible to the authenticated request. The result must not vary by connection state.
• tools/list remains paginated and tools should be returned in a deterministic order.
• Modern results carry resultType; tools/list also carries ttlMs and cacheScope.
• Tool input/output schemas accept JSON Schema 2020-12. List-change delivery moves to an opted-in subscriptions/listen stream.

Current dataplane gap

The Rust dataplane already federates and namespaces tools, but the current handler obtains backend transports from state created during the legacy initialize flow and keyed by downstream session. It therefore does not provide a complete MCP 2026-07-28 tools/list path.

Pagination is also incomplete (#4664), and backend tool-list changes are not yet relayed downstream (#5346).

Gateway work

• Route tools/list through the MCP 2026-07-28 stateless per-request path without requiring initialization or protocol-session state.
• Support the modern/legacy client and upstream combinations defined by [Major-1] Dual-stack stateless core protocol #5679 while keeping upstream legacy sessions internal to the gateway.
• Preserve current authorization, tool aliases, single-backend transparency, multi-backend namespacing, partial-backend failure handling, and capability filtering.
• Complete pagination across federated backends without dropping or duplicating tools and without corrupting cursors.
• Return deterministic aggregated ordering and the required resultType, ttlMs, and cacheScope; apply the aggregation and shared-cache rules from [Minor-2] Caching semantics: CacheableResult + deterministic ordering #5685.
• Preserve valid JSON Schema 2020-12 tool definitions without narrowing or lossy rewriting, coordinated with [Minor-5] Loosen tool schemas to full JSON Schema 2020-12 #5688.
• Validate and propagate the modern per-request metadata and required HTTP headers defined by [Major-1] Dual-stack stateless core protocol #5679 and [Minor-4] Required MCP request headers #5687.
• Advertise tools.listChanged only when the gateway can deliver opted-in changes through the negotiated protocol mechanism, coordinated with [Major-3] Notification rework: subscriptions/listen #5681 and [CF-DATAPLANE] Relay MCP list-changed notifications through gateway #5346.

Acceptance criteria

• A 2026-07-28 client can call tools/list through the Rust dataplane against a 2026-07-28 backend without initialize, notifications/initialized, or Mcp-Session-Id.
• Modern↔modern and supported cross-era gateway paths preserve tool discovery semantics.
• Single-backend names remain transparent; multi-backend names and explicit aliases remain deterministic and routable.
• Pagination covers every upstream page without omissions or duplicates and returns a valid downstream cursor contract.
• Repeated unchanged requests return the same tool ordering.
• Results contain valid resultType, ttlMs, and cacheScope, with private upstream data excluded from shared caches.
• JSON Schema 2020-12 tool definitions round-trip without loss.
• Required _meta fields and HTTP headers are validated; unsupported versions and header mismatches fail with the protocol-defined errors.
• listChanged is advertised only when delivery works for the negotiated protocol revision.
• Existing 2025-11-25 behavior remains compatible.
• Wire-level integration coverage exercises authenticated single-backend, federated, pagination, cache, schema, and deny paths; [TESTING][MCP-PROTOCOL]: Add Python SDK v2 live-stack E2E tests for MCP 2026-07-28 #5761 covers the SDK-level 2026 flow.

Related work

• Core stateless and dual-era routing: [Major-1] Dual-stack stateless core protocol #5679, [Major-2] Remove protocol-level sessions and SSE resumability from Streamable HTTP #5680
• Notification delivery: [Major-3] Notification rework: subscriptions/listen #5681, [CF-DATAPLANE] Relay MCP list-changed notifications through gateway #5346
• Cache metadata and deterministic ordering: [Minor-2] Caching semantics: CacheableResult + deterministic ordering #5685
• Request headers: [Minor-4] Required MCP request headers #5687
• JSON Schema 2020-12: [Minor-5] Loosen tool schemas to full JSON Schema 2020-12 #5688
• Dataplane pagination: [CF-DATAPLANE] MCP Protocol support for paginated responses from ListTools/ListResources/ListPrompts #4664
• End-to-end SDK coverage: [TESTING][MCP-PROTOCOL]: Add Python SDK v2 live-stack E2E tests for MCP 2026-07-28 #5761

Out of scope

• Tool execution through tools/call.
• Reimplementing the existing 2025-11-25 tool aggregation and namespacing behavior.
• Control-plane CRUD or Admin UI work unrelated to the dataplane wire path.