Epic: MCP protocol currency and 2026-07-28 stateless readiness

[JAORMX]

Goal

Bring ToolHive fully up to date with the MCP specification: complete the migration to the official modelcontextprotocol/go-sdk without functional loss, close our remaining gaps against the current stable spec (2025-11-25), and be ready for the breaking 2026-07-28 "stateless" revision (RC locked 2026-05-21, final ships 2026-07-28).

Hard requirement: ToolHive supports both revisions simultaneously. 2025-11-25 clients, servers, and backends keep working unchanged while 2026-07-28 peers are served natively — per-request version discrimination, not a cutover. This matches the SDKs' model (go-sdk v1.7 / TS SDK v2 serve both on the same endpoint). vMCP additionally acts as a cross-generation bridge: a client on either revision can reach backends on either revision, with vMCP translating between server-initiated requests and MRTR, resources/subscribe and subscriptions/listen, and session-ful vs handle-based state (design in the stateless-vMCP and MRTR sub-issues).

Spec context

• Stable revision is 2025-11-25. Our protocol ceiling is currently whatever our SDK negotiates.
• 2026-07-28 removes sessions (Mcp-Session-Id), the initialize handshake (per-request _meta + required server/discover), ping, logging/setLevel, SSE resumability, and all server-initiated requests (replaced by MRTR); deprecates roots/sampling/logging and DCR (→ CIMD); moves Tasks to an extension; adds required Mcp-Method/Mcp-Name headers, W3C trace context in _meta, and ttlMs/cacheScope caching metadata. See the draft changelog and RC announcement.
• SDK reality: go-sdk stable v1.6.1 targets 2025-11-25; v1.7.0-pre.1 targets 2026-07-28 (opt-in stateless). Ecosystem clients/servers will straddle both revisions for a long time — this is a dual-protocol effort, not a cutover.

Workstreams

A. Loss-free SDK migration (in flight)

The migration off mark3labs/mcp-go (#5729, via toolhive-core's mcpcompat shim) is the gateway to everything else. An audit found shim regressions; fixes and the test gate are tracked and must land so #5729 merges with zero functional loss.

B. 2025-11-25 compliance gaps

Verified gaps in the proxies, middleware, and vMCP against the current stable spec — mostly server→client message flows, pagination, prompts, and parser blind spots.

C. 2026-07-28 stateless readiness

Design work can start now; landing is gated on the spec going final and go-sdk v1.7 stabilizing. Freeze new investment in deprecated surfaces (roots, sampling, logging/setLevel, DCR, HTTP+SSE, SSE resumability); shape new work (e.g. elicitation/sampling passthrough) MRTR-first.

Ordering

1. Workstream A gates everything (shim fixes → regression tests → feat: migrate from mark3labs/mcp-go to toolhive-core/mcpcompat (go-sdk) #5729 merges).
2. Workstream B items are independent of each other; the streamable server→client channel unblocks the two list_changed items.
3. Workstream C starts with go-sdk v1.7 adoption; parser vocabulary and telemetry items can proceed in parallel once the design lands.

Sub-issues below track the individual work items.

Expected follow-ups (not yet filed as issues)

These are identified and scoped but deliberately not opened yet — they become actionable only once the stateless design docs (#5755/#5756) land and the 2026-07-28 spec + go-sdk v1.7 go final. File them then (details preserved in the closed placeholders linked):

• Parser/middleware 2026-07-28 vocabulary (Teach MCP parser middleware the 2026-07-28 protocol vocabulary #5757): server/discover, subscriptions/listen, MRTR result shapes, _meta protocol fields, Mcp-Method/Mcp-Name headers, error-code renumbering.
• MRTR-based elicitation/sampling passthrough in vMCP (Design MRTR-based elicitation and sampling passthrough for vMCP #5759): design MRTR-first; also covers today's missing sampling passthrough.
• Auth: CIMD-first registration + RFC 9207 issuer validation (Auth readiness for 2026-07-28: CIMD-first registration and RFC 9207 #5760).
• Caching metadata (ttlMs/cacheScope) in vMCP (Support MCP caching metadata (ttlMs/cacheScope) in vMCP #5761).
• Any-JSON structuredContent (Accept any JSON value as structuredContent in vMCP #5762): small; can be picked up early alongside SEP-2106 types.
• Embedded AS polish: RFC 7592 + introspection (Complete embedded AS surface: RFC 7592 management and introspection #5753): backlog; DCR deprecation caps the investment.

Generated with Claude Code