Support MCP 2026-07-28 spec (go-sdk v1.7 via toolhive-core)

[JAORMX]

Summary

Part of #5743 (Workstream C). Advances #5754.

The goal is support for the new MCP spec revision, 2026-07-28 ("stateless") — not a Go SDK for its own sake. Bumping toolhive-core to v0.0.34 pulls in go-sdk v1.7.0-pre.3, the SDK that implements 2026-07-28, so vMCP can negotiate and speak both revisions per backend (Legacy 2025-11-25 + Modern 2026-07-28). The build is unchanged (the mcpcompat shim absorbs the go-sdk API change); this PR fixes the behavioral gaps that only surface once the real v1.7 SDK is imported, without regressing 2025-11-25 (dual-revision is a hard requirement).

Note / CC @jhrozek: this supersedes the prior "hand-roll the Modern envelope, don't import go-sdk v1.7 into the root module" approach (#5981). Importing the SDK is what makes the new spec actually reachable — you can't speak 2026-07-28 without the SDK that implements it. Flagging because it changes the probeRevision/classification design you authored (#5913 / 885e8b14).

What changed

• Revision classification (the crux). Decide a backend's revision by whether its server/discover result advertises 2026-07-28 in supportedVersions — the SEP-2575 negotiation signal, and exactly what go-sdk's own reference client keys on (mcp/client.go:428-444). The old "any clean server/discover ⇒ Modern" heuristic mis-classified stateful 2025-11-25 backends, which under v1.7 answer discover too (negotiating down) → their Legacy tools/list was parsed as Modern → sessions died. New sentinel errModernNegotiatedDown routes the negotiate-down case through the existing reclassify-on-mismatch machinery (retry-safe: only read-only discover/list can produce it).
• Reserved-_meta egress strip. Strip the per-hop io.modelcontextprotocol/* control keys at both Legacy backend tool-call egresses (httpBackendClient.CallTool, mcpSession.CallTool) — a stateful backend 400s them under v1.7. Exact keys only, copy-before-mutate, no-op for Legacy.
• Test adaptations + pins. Real v1.7 client is server/discover-first over SSE (parser assertion made transport-aware); the SSE-forwarding fake now answers discover with -32601; a nil-registry test-construction fix; and new real-backend pin tests asserting stateful → Legacy / stateless → Modern so a future SDK discover-semantics change fails loudly here, not as mystery failures.
• Cleanup: reword the placeholder ponytail: comments to NOTE:.

Type of change

• Dependency update enabling new protocol support (+ the behavioral fixes it surfaces)

Test plan

• Unit tests (task test)
• Linting (task lint-fix)

The full suite goes from 137 failures to exactly the 3 pre-existing, sandbox-environment failures (no container runtime ×2, no keyring ×1 — none in touched packages). New/changed tests pass under -race.

Special notes for reviewers

• Reviewed by a 3-way Opus panel — protocol-correctness/dual-revision (headline), security, and test-quality. The protocol reviewer verified every load-bearing claim against the actual go-sdk v1.7.0-pre.3 source (the SupportsProtocolVersion stateless gate at mcp/streamable.go:871, the supportedVersions JSON tag, the reference-client fallback). Verdict: SHIP / SHIP-WITH-NITS ×2, no MUST-FIX. All actionable nits addressed (added a StripReservedModernMeta unit test, a version-exact-match tripwire comment, and filed the cache-staleness follow-up).
• Known, characterized limitation → vMCP backend revision cache has no success/TTL re-probe (stale on stateless redeploy) #5992: the revision cache self-corrects on error (Modern→Legacy redeploys) but not on success, so a Legacy→stateless redeploy leaves the cached label stale (wire behavior stays correct via SDK negotiation; it's telemetry/handshake-overhead, not correctness). A TTL re-probe is deferred to vMCP backend revision cache has no success/TTL re-probe (stale on stateless redeploy) #5992.
• probeRevision deliberately builds its own discover client (rather than delegating) so a transport-misconfiguration hard-fails instead of being mis-cached as Legacy — see the doc comment.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 98.18182% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 72.10%. Comparing base (cfa2b40) to head (ab6d5f2).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
pkg/vmcp/client/modern.go	93.33%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5993      +/-   ##
==========================================
- Coverage   72.10%   72.10%   -0.01%     
==========================================
  Files         718      719       +1     
  Lines       74465    74526      +61     
==========================================
+ Hits        53695    53735      +40     
- Misses      16921    16962      +41     
+ Partials     3849     3829      -20     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[JAORMX]

Context vs the #5754 gate (proceeding on pre.3 — deliberate maintainer decision)

Flagging this explicitly for reviewers since it touches the go/no-go analysis on #5754:

• This adopts go-sdk v1.7.0-pre.3 (via toolhive-core v0.0.34), ahead of the "adopt when v1.7.0 final" consumability gate in Adopt go-sdk v1.7 for MCP 2026-07-28 stateless support #5754. This is a deliberate decision to move now (final is ~2026-07-28); the v0.0.34 tag was cut manually. Re-pinning to a final-built toolhive-core release once v1.7.0 ships is a trivial follow-up.
• It does NOT trigger the two regressions Adopt go-sdk v1.7 for MCP 2026-07-28 stateless support #5754 warns about. It intentionally keeps the hand-rolled modern_envelope.go and the client modernCall path — it does not swap to the SDK-backed stateless client/server. So:
  • cacheScope: "private" is preserved (no cross-identity cache leak — the envelope still hardcodes it; the SDK's setDefaultCacheableValues() "public" default is never reached).
  • The RFC-0083 D6 per-call-auth / poolable connection model is untouched (no per-(principal, backend) SDK session introduced).
• What it is: the parser/version-negotiation slice of v1.7 — correctly classifying each backend's revision by server/discover supportedVersions (the SEP-2575 signal), plus the reserved-_meta egress strip, fixing the 137 failures that surface once the shim is discover-first under real v1.7. The Modern-envelope deletion (Phase 2) and the SDK-backed-client swap are explicitly out of scope and remain gated as Adopt go-sdk v1.7 for MCP 2026-07-28 stateless support #5754 describes.

Reviewed by a 3-way Opus panel (protocol-correctness/dual-revision headline) with every load-bearing claim verified against the real go-sdk v1.7.0-pre.3 source. cc @jhrozek

[jhrozek]

Went through this one carefully. The core change is right: keying on supportedVersions is the correct normative signal (the field is required in the draft DiscoverResult schema), and the reserved _meta strip is right in both direction and coverage. I checked every other Legacy egress and they all pass nil caller meta, so CallTool really is the only one that needed it, and both of its implementations are covered.

I've opened #5997 stacked on this branch with the follow-ups rather than dumping them on you as review comments, since a couple turned into real code changes. Happy for you to take it, cherry-pick from it, or tell me to drop it.

Two things in there are actual bugs, both cases where the same "is this peer Modern?" question still gets answered by the rule this PR replaces:

-32022 is treated as proof of Modern in isModernProtocolCode, but it means the opposite, that the peer doesn't support the version we asked for. A backend answering it gets cached Modern permanently and enumerates zero capabilities, silently: modernListCapabilities tolerates the error as caps == nil, and errModernProtocolError isn't in isRevisionMismatch, so nothing ever re-probes it. Worth noting go-sdk's own client decodes data.supported here and falls back to initialize; its test for the case is literally named "unsupported protocol version falls back to initialize". So this PR ends up in the odd spot where a backend saying "I don't do 2026-07-28" via supportedVersions correctly goes Legacy, but the same backend saying it via -32022 goes Modern-with-nothing.

The other is that probeRevision doesn't look at TransportType at all, so it POSTs a Modern discover at sse targets too. For ToolHive-proxied SSE backends this already lands on Legacy via the 405, so it's mostly a wasted round trip, but for a remote SSE server that doesn't reject the POST it can hang until the client timeout, and since errModernTransient is never cached that repeats on every single call.

The rest is smaller. Five comments still justify the hand-rolled Modern shim with "go-sdk v1.6.1 can't express this", which is the premise this PR invalidates, and the revisions cache comment still promises self-healing that no longer happens in the Legacy->Modern direction. Also filled the isRevisionMismatch truth-table row for errModernNegotiatedDown and added a test for the mcp_session.go strip site, which was the one of the two that had no coverage.

One thing I deliberately left alone: the stale-Legacy cache. Your reclassify test correctly pins the new behavior, I just amended the comment, because the staleness isn't purely internal. CachedRevision feeds health/status.go:260 and gets republished into the mcpRevision CRD field on every health tick, so a backend redeployed stateful->stateless reports 2025-11-25 indefinitely. #5992 covers it. There may be a cheaper fix than a TTL re-probe: initializeClient already gets InitializeResult.ProtocolVersion back and throws it away, so the SDK-negotiated value might just be readable in-band. Would need checking whether initialize even runs once Connect() has already negotiated Modern via discover.

Two upstream things also fell out of this that aren't yours to fix. mcpcompat's SSE server advertises 2026-07-28 because that transport has no ProtocolVersionSupporter gate (only streamable does), which is why the client negotiates Modern over a 2024-11-05 transport in parser_integration_test. And mcpcompat/client.Initialize passes nil options to Connect, so a caller's requested ProtocolVersion is silently ignored and latestProtocolVersion always wins. That's why the test asking for 2024-11-05 changed behavior on this bump. I'll write those up separately.

[JAORMX]

Rebased onto current main (cfa2b406) to resolve a conflict introduced by #6001.

What conflicted: #6001 ("Fall back to Legacy on an inconclusive vMCP revision probe") changed dispatch in pkg/vmcp/client/client.go — the same probe/classify path this PR reworks. The only textual conflict was the probeRevision doc comment. Resolved in favour of #6001's wording, which accurately describes the now-current behaviour: dispatch (the sole caller) falls back to Legacy uncached on any probeRevision error. That still honours this PR's original concern — an uncached fallback means a transport misconfig or a negotiate-down is never permanently mis-cached as Legacy; a genuinely Modern backend re-probes on the next call. The errModernNegotiatedDown → Legacy classification and the reserved-_meta egress strip are unchanged.

Also dropped: the CRD-docs regen commit (ca1198a6) — its contents already landed on main via #5999, so the rebase dropped it as empty. The nil-registry test fix (also carved into #5999) merged cleanly. Net: a single commit, 13 files.

Verified locally: task lint-fix → 0 issues; task test → only the 3 known sandbox-env failures (container runtime ×2, keyring ×1), none in touched packages.

🤖 Rebased with Claude Code

[jhrozek]

One design question I hit while reviewing, which I didn't want to change unilaterally in the stacked PR.

ReservedModernMetaKeys is doing two jobs: it's the list of keys we strip on the way out to a backend, and also the list that means "this request is Modern" on the way in (hasModernSignal).

That's a trap for whoever adds the next key, and there already is one. io.modelcontextprotocol/logLevel is a real fourth reserved per-request key — it's in the draft's per-request table and go-sdk declares it at protocol.go:2370. Adding it to the list would strip it correctly, but would also start rejecting any request that carries it without a protocolVersion — requests that work today and that go-sdk itself accepts (validateRequestMeta gates purely on protocolVersion), for a field SEP-2577 already deprecates.

Want to split it into two lists, so "strip this key" and "this key means Modern" are separate decisions? I left logLevel out of #5997 rather than change your design without asking.

[JAORMX]

Want to split it into two lists, so "strip this key" and "this key means Modern" are separate decisions?

Yes — good catch, done in this PR (commit ab6d5f2d, on top of your #5997 merge). You're right that the coupling is a trap and that logLevel is the key that springs it.

Split into two:

• ReservedModernMetaKeys — the egress/strip set. Now includes io.modelcontextprotocol/logLevel, so it's stripped before a Legacy hop (and mergeModernMeta strips a caller's copy before overlaying vMCP's authoritative meta). Consumed by StripReservedModernMeta + the Modern-client overlay.
• modernSignalMetaKeys — the ingress/detection set read by hasModernSignal. Unchanged three keys (protocolVersion, clientInfo, clientCapabilities); logLevel deliberately excluded, matching go-sdk's validateRequestMeta (gates purely on protocolVersion) and the SEP-2577 deprecation.

I kept clientInfo/clientCapabilities in the signal set rather than narrowing to protocolVersion-only, so classification behavior is byte-for-byte what it was — the split is purely about making logLevel (and any future strip-only key) addable without turning it into a false Modern signal. If you'd rather the signal set narrow to protocolVersion alone to track go-sdk exactly, that's a separate, easy follow-up — say the word.

Added a ClassifyRevision truth-table row pinning logLevel-alone ⇒ Legacy as a tripwire (fails loudly if anyone re-points hasModernSignal at the strip set), and seeded logLevel into both the StripReservedModernMeta unit test and the real-backend egress test so the stripping is actually exercised. task lint-fix clean; task test green except the 3 known sandbox-env failures.

🤖 via Claude Code

[jhrozek]

LGTM. The strip/signal split is exactly right, and the ClassifyRevision row pinning logLevel-alone => Legacy is the part I'd have asked for — it's the tripwire that catches someone re-merging the two lists later.

I re-reviewed the full branch after the #5997 merge and ran ./pkg/mcp/... and ./pkg/vmcp/... locally against ab6d5f2d1; all green. Spot-checked that hasModernSignal is the only consumer that needed repointing at the new signal set, and that the remaining ReservedModernMetaKeys readers all genuinely want the strip semantics.

One nit, not worth holding the PR for, so I've filed it as #6002 item 1: the strip set is applied on the Modern egress too, via mergeModernMeta, and ModernRequestMeta doesn't re-supply logLevel — so a caller's logLevel is now dropped on Modern hops as well, where before it passed through. I think that's the right behavior (vMCP is the backend's peer, and SEP-2577 deprecates logging), but ReservedModernMetaKeys' doc still says "before a Legacy (session-based, stateful) backend hop", which points the other way. A sentence and a mergeModernMeta test row would make it a stated decision rather than a side effect.