Adopt go-sdk v1.7 for MCP 2026-07-28 stateless support

[JAORMX]

Part of #5743 (Workstream C: 2026-07-28 stateless readiness). Gating issue for this workstream.

Work

The 2026-07-28 revision ships as go-sdk v1.7.x (v1.7.0-pre.1 already implements it; stateless is opt-in via StreamableHTTPOptions.Stateless, and endpoints negotiate down to 2025-11-25 for old clients). ToolHive consumes go-sdk through toolhive-core's mcpcompat shim.

• Track go-sdk v1.7.0 final; evaluate the changelog and the MCPGODEBUG escape hatches (removed in v1.9.0).
• Determine what the mcpcompat shim needs to expose: the Stateless option, server/discover, MRTR result shapes, subscriptions/listen, per-request _meta protocol fields.
• Bump toolhive-core → go-sdk v1.7.x, then ToolHive → toolhive-core, behind the regression-test gate from Add regression tests gating the mcp-go to go-sdk migration #5742.

Depends on: #5729, stacklok/toolhive-core#156, #5742.

[JAORMX]

go-sdk v1.7 adoption: go/no-go evaluation

Spike result. Grounded in the go-sdk v1.7.0-pre.3 source, the mcpcompat shim (toolhive-core v0.0.32), and the ToolHive tree; adversarially reviewed for MCP-protocol correctness, library-reuse, feasibility, and security.

Question that triggered this spike: should we keep hand-rolling Modern (2026-07-28) wire code in ToolHive (#5910 already did; #5911 was about to), or invest in this upgrade that implements stateless natively?

Verdict: GO on the direction, NO-GO on doing it now as a ToolHive change. The upgrade is the correct strategic move and it does eliminate a meaningful chunk of hand-rolled code — but it is (a) not a ToolHive PR at all, (b) gated on an unreleased SDK, and (c) far less of a "delete it all" win than the naive framing suggests. Pausing #5911's hand-rolled client transport was the right call; the clean client path is SDK-provided once the upgrade lands.

---

What go-sdk v1.7 genuinely delivers (verified in v1.7.0-pre.3 source)

• Stateless server, one bool: StreamableHTTPOptions.Stateless (mcp/streamable.go:146). POST-only; GET/DELETE → 405. 2026-07-28 over HTTP is accepted only when Stateless=true (a stateful handler caps at 2025-11-25 — you cannot have stateful Modern).
• Discover-based client with automatic downgrade: Client.Connect (mcp/client.go:307) tries server/discover first at version ≥ 2026-07-28, falls back to legacy initialize at 2025-11-25 when discover returns a non-negotiable error, and retries once only on -32022 when the server advertises a mutually-supported Modern version. Per-request _meta triple is injected automatically (client.go:522). This is the exact behavior Handle per-backend MCP revision in vMCP (client-side dual protocol) #5911 was going to hand-roll as a raw POST — the SDK does it natively.
• server/discover is SDK-native on both ends (server.go:884, registered :1783) — returns SupportedVersions + capabilities. (server/discover is answered even by a stateful server — it's exempt from the stateful-Modern rejection — but Modern operational requests still require Stateless=true.)
• Standardized error codes exported: -32022/-32021/-32020 (shared.go:388), ResourceNotFound moved -32002→-32602. These match ToolHive's hand-rolled constants in pkg/mcp/revision.go line-for-line.
• MRTR with an opt-out (MultiRoundTripOptions.Disabled); input-required consumable via exported CallToolResult.NeedsInput().
• Module cost is benign: go-sdk needs go 1.25.0 (ToolHive is on 1.26); only adds golang.org/x/time + golang.org/x/sync.

Why "v1.7 makes the hand-rolled code go away" is only partly true

1. It is not a ToolHive change. ToolHive imports zero go-sdk directly — everything routes through mcpcompat (~58–61 non-test consumers; the one go-sdk grep hit is a comment at pkg/mcp/revision.go:55). The upgrade is a toolhive-core (separate repo) deliverable first: adopt v1.7, expose a WithStateless server option, surface Modern wire types + -3202x codes, and add a Modern (no-initialize) client path — then ToolHive bumps toolhive-core. Two coordinated PRs across two repos. (Precise mechanism: a direct require go-sdk v1.7 in ToolHive while toolhive-core still requires v1.6.1 would not necessarily fail to compile — the ~12 gosdk symbols the shim uses still exist in pre.3 — but it would run the shim against an SDK it was neither written nor tested against, with already-drifted wire values, and still expose none of the Modern API ToolHive needs. The blocker is "unvalidated SDK + unexposed API," not a mechanical build break.)

2. v1.7.0 is not final and the wire surface is still moving. Only pre.1/2/3 exist (atypical — most minors shipped a single pre at the final SHA). Per the changelog, pre.3 changed DiscoverResult._meta, added a subscriptions/listen result type, and started emitting resultType — exactly the interop surface we'd depend on (features present in pre.3 source; the per-pre-release deltas are changelog-derived, not source-diffed here). In-tree corroboration: pkg/mcp/revision.go notes the current SDK is pinned to draft 2026-06-30 with CodeHeaderMismatch=-32001, while pre.3 already uses -32020. Pinning a production shim to pre.3 is not advisable. The MCPGODEBUG escape hatches introduced in 1.7.0 are (per this issue / the SDK's mcpgodebug doc) removed in 1.9.0 — do not build the shim on any of them.

3. No exported client protocol-version pin — a functional blocker for Handle per-backend MCP revision in vMCP (client-side dual protocol) #5911, not a nice-to-have. ClientSessionOptions.protocolVersion is unexported and doc-flagged "for testing" (client.go:251); the client always starts at latest and negotiates down. Handle per-backend MCP revision in vMCP (client-side dual protocol) #5911's core requirement — forcing a per-backend revision — cannot be expressed via the SDK client's public API at all; it can only be inferred from what the backend advertises. Per-backend control therefore needs either a shim-level pin or an upstream ask to export the field (recommended).

4. Much of ToolHive's Modern code is admission/authz/audit policy the SDK will never replace. Of ~2258 hand-rolled prod LOC, only modern_envelope.go (~561 LOC) is cleanly SDK-replaceable wire code — and even that is conditional. The dispatch authz-gate re-homing + audit "denied" labeling (modern_dispatch.go:209-449), classification-at-the-admission-seam (so a gated Modern request audits as denied, not a 200 tool-error), parser Modern vocab feeding authz/audit/tool-filter middleware, transport-proxy revision handling (routing-token minting, initialize-free Modern readiness, method gating), and the per-identity cacheScope:"private" policy all stay regardless.

5. The envelope is a deliberate SDK bypass, not a stopgap — and deleting it is a security gate. modern_envelope.go is self-described as a durable serializer: the SDK sets resultType/_meta.serverInfo inside the ServerSession dispatch that vMCP deliberately bypasses for stateless Modern (to keep per-identity admission filtering). Concrete regression risk (verified): the SDK's setDefaultCacheableValues() (protocol.go:1195) sets CacheScope="public" unconditionally and unexported, and is called by the SDK's built-in list handlers. ToolHive hardcodes cacheScope:"private" + Cache-Control: private, no-store (modern_envelope.go:89-102) as a deliberate anti-cache-poisoning divergence — per-identity admission-filtered views must not be cacheable cross-identity. So a Phase-2 "delete the envelope, marshal SDK result types" would silently regress cacheScope to "public" (a cross-identity cache leak) unless vMCP keeps custom list handlers that bypass the SDK's built-in listers — i.e. keeps most of the envelope. Phase 2 envelope deletion is therefore gated on preserving private cacheScope through custom handlers, not just on "reconciling the admission model."

One near-term unblock worth noting (narrow)

Server-side stateless serving rides a flag (StreamableServerTransport.Stateless) that already exists in v1.6.1 but mcpcompat hardcodes Stateless:false (transports.go:546) with no option — so a WithStateless shim option is a surfacing gap, not a version gap. But be precise about what it buys: on v1.6.1 it grants stateless serving for 2025-11-25 only — zero Modern capability (Modern wire types/codes require v1.7). Its real value is exercising the shim's stateless projection/rehydration no-op path ahead of Phase 1, not serving Modern. Low-risk toolhive-core increment that doesn't wait on v1.7 final, but it is de-risking, not a feature.

Gate status (both green)

• feat: migrate from mark3labs/mcp-go to toolhive-core/mcpcompat (go-sdk) #5729 (mcp-go → go-sdk migration): fully merged — no mark3labs/mcp-go, toolhive-core v0.0.32 + go-sdk v1.6.1 indirect.
• Add regression tests gating the mcp-go to go-sdk migration #5742 regression tests: present across pkg/vmcp/server/*_regression_test.go, pkg/vmcp/client/auth_error_mapping_regression_test.go, test/integration/vmcp/*, pkg/transport/proxy/transparent/*.

Recommendation / next actions

1. Do not write more speculative hand-rolled Modern code in ToolHive. Handle per-backend MCP revision in vMCP (client-side dual protocol) #5911's client transport would be throwaway — the SDK's discover-first Connect is the clean replacement once mcpcompat exposes a Modern client path.
2. Sequence this issue as core-gated, two-phase:
   • Phase 1 (toolhive-core, separate PR): adopt go-sdk v1.7 when final (not pre.3); add WithStateless; surface Modern wire types + -3202x codes; add the discover-based Modern client path; make the per-session projection/rehydration path no-op cleanly under stateless. Cut a toolhive-core release.
   • Phase 2 (ToolHive, small + downstream): bump toolhive-core; simplify modern_dispatch.go routing and delete the pure-wire-serialization parts of modern_envelope.go — only behind the security gate that per-identity cacheScope:"private" is preserved via custom list handlers; drop the Remove the vMCP Modern stateless dispatch kill-switch before GA #5959 kill-switch. Keep all authz/audit/classification/proxy policy. Realistically a partial shrink, not a wholesale delete.
3. Track go-sdk v1.7.0 final; open an upstream ask to export the client protocol-version pin (needed for Handle per-backend MCP revision in vMCP (client-side dual protocol) #5911 per-backend forcing). Do not depend on any MCPGODEBUG hatch (gone in 1.9.0).
4. Handle per-backend MCP revision in vMCP (client-side dual protocol) #5911 (per-backend revision) is effectively shim-gated — its clean implementation needs the mcpcompat Modern client path, and even the era probe needs a Modern client call. Recommend deferring Handle per-backend MCP revision in vMCP (client-side dual protocol) #5911 until Phase 1 lands rather than hand-rolling.
5. Optional near-term increment: land the WithStateless server option in mcpcompat now (rides the existing v1.6.1 flag) to de-risk Phase 1, without waiting on v1.7 final.

Generated with Claude Code.

[jhrozek]

Decision note: adopting v1.7 lets us delete two hand-rolled Modern marshalers — but validate the connection-model tradeoff first

Capturing this so it isn't re-derived from scratch when this issue is picked up. As of the vMCP Modern work (#5953, #5980), we now hand-roll the 2026-07-28 wire shape on both edges, deliberately bypassing the SDK-backed path:

• Server edge — pkg/vmcp/server/modern_envelope.go (from Serve MCP 2026-07-28 Modern stateless requests through vMCP #5953): a from-scratch resultType/_meta.serverInfo/cacheScope serializer, matched byte-for-byte to go-sdk v1.7.0-pre.3.
• Client edge — pkg/vmcp/client/modern.go modernCall (from Handle per-backend MCP revision in vMCP (client-side dual protocol) #5980): raw-HTTP Modern requests with its own envelope decode, -32020 handling, and reserved-_meta stripping.

toolhive-core already has the machinery that would replace both:

• Server: mcpcompat/server.WithStateless(bool) (core feat(authz): Add YAML support for CedarConfig #187, merged) — go-sdk answers server/discover / per-POST temp sessions natively.
• Client: the mcpcompat client + NeedsInput() / WithoutMultiRoundTrip() / -3202x constants (core Add unit tests for environment package #189, open).

So v1.7 adoption is a real simplification — delete both hand-rolled marshalers and let go-sdk own the wire shape. But it's a fork of the current bypass architecture, and it is NOT free:

1. It cuts against vMCP's connection model (RFC-0083 D6). The Modern paths are deliberately per-request / poolable / zero-retained-credential-state (auth applied per call via OBO/header-inject/token-exchange). The SDK-backed client/server bakes auth in at construction/initialize. Before betting on the swap, validate that go-sdk's stateless client AND server modes support per-call auth injection without a per-(principal, backend) client/session. If they don't, un-forking costs the pooling model that statelessness exists to enable — a step to more machinery, not less.
2. The orchestration stays regardless. Per-backend era detection (probe Modern-first via server/discover, fall back to Legacy initialize, re-classify on -32601/404/-32020) sits above any single client and is not simplified by swapping the client underneath it.
3. cacheScope: private must survive the swap. Our hand-rolled envelope hardcodes cacheScope: private to stop one identity's admission-filtered view being cached for another (core registry: Add target port to Server struct #188 fixes the same leak on the WithStateless path). Any adoption must pull in registry: Add target port to Server struct #188 (or confirm the SDK path emits private), or it reintroduces a cross-identity cache leak.

Consumability gate (independent of desirability): needs go-sdk v1.7.0 final + a toolhive-core release past #185/#187 (and #189 merged). thv currently pins toolhive-core v0.0.32, which predates that work, and core's release.yml blocks tagging while go-sdk is a -pre/-rc.

Bottom line: treat "un-fork to the SDK-backed client+server" as one decision spanning both edges, taken here — not as a per-PR cleanup on #5980/#5953. First concrete task if we pursue it: prove go-sdk's stateless modes support per-call auth without a per-principal client; if that fails, the hand-rolled marshalers stay and this issue narrows to the parser/telemetry/version-negotiation parts of v1.7.