Close mcpcompat functional gaps vs mcp-go for a loss-free migration

[JAORMX]

Context

stacklok/toolhive#5729 migrates ToolHive from mark3labs/mcp-go v0.55.1 onto the mcpcompat shim (introduced in #150, released in v0.0.27, backed by modelcontextprotocol/go-sdk v1.6.1). A code-level audit of the shim against ToolHive's actual mcp-go usage found functional regressions — some disclosed in that PR, some not. ToolHive wants to complete the migration (it is the path to MCP 2026-07-28 / stateless support via go-sdk v1.7.x) without accepting any functional loss.

We verified that no newer go-sdk release helps: latest stable is v1.6.1, latest overall is v1.7.0-pre.1, and the relevant API surface is identical in both. Every fix below is therefore shim-side work against v1.6.1, except where noted as an upstream ask.

Audit findings (shim v0.0.27, file references are mcpcompat/)

#	Finding	Status	Evidence
1a	Client never registers ProgressNotificationHandler / LoggingMessageHandler (both exist in go-sdk v1.6.1 ClientOptions) — only the 3 list_changed handlers are wired. Combined with 1b, no server-initiated notification survives the ToolHive stdio bridge end-to-end	Lost — shim bug	client.go:417-427
1b	Server side forwards only progress + message notifications; tools/list_changed and everything else is dropped (go-sdk has no public generic notification sender)	Lost — upstream API gap	notifications.go:32-76
2	WithHeartbeatInterval is a silent no-op: the interval is stored and never used; go-sdk StreamableHTTPOptions has no keep-alive. Long-lived SSE streams get no pings and can be dropped by LB idle timeouts	Lost — undisclosed	transports.go:85,142-143
3	SessionIdManager is largely wired (Generate via GetSessionID, Terminate via DELETE, Validate on cross-replica rehydration) but per-request Validate is skipped for local sessions — mcp-go validated every request. A session terminated cross-pod or via auth-failure can keep being served by the origin pod	Degraded	server.go:334-336, transports.go:154,199-208,216,233
4	401/auth errors are string-matched ("401", "unauthorized"); extractResourceMetadataURL always returns ""; 403-on-initialize is not mapped to ErrLegacySSEServer. The sentinels ToolHive consumes are produced, so impact is low today	Degraded	errors.go:66-93
5	go-sdk enables DNS-rebinding/localhost protection by default; the shim does not expose DisableLocalhostProtection. Local proxies with custom Host headers now get 403 (mcp-go had no such protection)	Behavior change	transports.go:166,170
6	go-sdk paginates tools/list at DefaultPageSize=1000; mcp-go returned everything. Non-cursor-following clients see silent truncation past 1000 tools	Behavior change	go-sdk server.go:35-36
7	Per-session dynamic tool projection (security-relevant for vMCP): genuinely implemented — per-session go-sdk Server + live AddTool/RemoveTools reconciliation	Kept (needs runtime validation)	server.go:298,375-423, session.go:122-239
8	Doc comments claim progress/logging notifications are forwarded (they are not, see 1a) and the WithSessionIdManager comment says it is unwired (it mostly is wired)	Docs wrong	client.go, notifications.go, transports.go:135-136

Work items

Shim fixes (target: v0.0.28)

• 1a. Register client notification handlers — wire go-sdk's ProgressNotificationHandler + LoggingMessageHandler into the mcpcompat client and route to the compat notification callback. Cheapest fix, largest correctness gain.
• 1b. list_changed via feature re-sync — instead of forwarding the raw notification (impossible without a generic sender), re-sync the mirrored tools/resources/prompts on upstream list_changed; go-sdk auto-emits list_changed to clients on feature mutation. This restores (and arguably improves) mcp-go semantics without waiting on upstream.
• 2. Implement keep-alive shim-side — honor WithHeartbeatInterval by injecting SSE comment lines (: keepalive) on a ticker into text/event-stream responses via a ResponseWriter wrapper around the go-sdk handler. SSE comments are spec-legal and ignored by clients.
• 3. Per-request Validate for local sessions — Mcp-Session-Id is visible at the shim's HTTP layer before delegation to the go-sdk handler; call Validate on every request regardless of session locality, restoring mcp-go semantics (cross-pod/auth-failure termination takes effect immediately).
• 4. Adopt StreamableClientTransport.OAuthHandler — replace 401 string-matching with go-sdk's native OAuth flow hook (exists in v1.6.1); populate AuthorizationRequiredError.ResourceMetadataURL; map 403-on-initialize to ErrLegacySSEServer.
• 5. Expose DisableLocalhostProtection — plumb the option through shim config so callers can preserve pre-migration behavior for local proxies (default should keep protection on; ToolHive opts out only where it fronts localhost with custom Host headers).
• 6. Configurable server page size — expose go-sdk's page size so aggregating servers (vMCP) can raise it; document that clients must follow cursors (client-side cursor loops are tracked in ToolHive, not here).
• 7. Fix the false doc comments from finding 8.

Upstream asks (file against modelcontextprotocol/go-sdk, non-blocking)

• Public generic notification sender on ServerSession (unblocks true notification passthrough; only typed NotifyProgress/Log exist today).
• Server-side keep-alive option in StreamableHTTPOptions.
• Typed HTTP-status errors from transports (removes string-matching).

Acceptance criteria

• ToolHive adds regression tests (tracked in stacklok/toolhive) that fail against v0.0.27 and pass against v0.0.28: bridge end-to-end forwarding of progress/message/list_changed, cross-pod session termination taking effect on the origin pod, SSE keep-alive presence on idle streams, >1000-tool listing behavior.
• feat: migrate from mark3labs/mcp-go to toolhive-core/mcpcompat (go-sdk) toolhive#5729 bumps to the fixed release and merges with those tests green — i.e. the mcp-go → go-sdk migration lands with zero functional loss.
• Runtime validation of per-session tool projection (finding 7) performed as part of the ToolHive-side test work.

Why now

The 2026-07-28 stateless MCP revision ships this month; go-sdk v1.7.x is the only Go SDK line with support for it. The shim is the bridge that lets ToolHive get there — these gaps are the only thing standing between us and a loss-free migration.

Generated with Claude Code

[JAORMX]

Second verification pass — additional findings (2026-07-08)

An independent second audit of shim v0.0.27 confirmed all findings above and surfaced six additional regressions not in the original table. Three of these (U1, the full notification loss, U3) should be treated as merge blockers for stacklok/toolhive#5729.

#	Finding	Status	Evidence (mcpcompat/)
U1	vMCP initialize no longer advertises tools/resources capabilities. WithToolCapabilities/WithResourceCapabilities flags are stored as informational only and never mapped to go-sdk ServerOptions; go-sdk derives capabilities from registered features at initialize time, but vMCP registers all tools per-session after the initialize result is produced. Net: initialize advertises only {logging}. Spec-compliant clients that gate tools/list on capabilities.tools see zero tools. (e2e tests miss this because the shim client calls ListTools unconditionally.)	CRITICAL — Lost	server.go:106-112,200-215,417-419; go-sdk server.go:557-595
U2	Backend session-ID hint replay is dead. transport.WithSession(hint) is accepted but Initialize builds the go-sdk transport without the preset session ID and then overwrites the hint with the freshly-minted one. Every cross-pod restore/cache-evict reconnect mints a new backend session — stateful backend sessions reset; old ones leak until backend TTL.	HIGH — Lost	client.go:119-141 vs mcp-go streamable_http.go:645-647; consumer pkg/vmcp/session/internal/backend/mcp_session.go:368
U3	Request-context bridge keyed by session ID → cross-request context bleed (security). One pending HTTP request context is stored per session and bridged into the detached handler goroutine; two concurrent POSTs on the same session clobber/clear each other. Consequences: audit/telemetry/identity attributed to the wrong request; worst case, a holder of a stolen session ID can time requests so identity binding evaluates against the owner's context — a bypass race that did not exist under mcp-go (per-request synchronous contexts).	HIGH — security race	transports.go:191-194, server.go:388-399,171-181
U4	Mid-call elicitation may never reach the client. Shim forces JSONResponse=true; go-sdk delivers server→client requests made during a JSON-responding POST only to the standalone GET stream "if any". Clients that never open a hanging GET block composite-workflow elicitation until timeout (mcp-go delivered it on the POST's own SSE stream). Related: go-sdk hard-gates Elicit on the declared client capability; rehydrated sessions force-seed that capability (timeout instead of fail-fast) and answer POSTs in SSE mode (Content-Type differs by pod).	HIGH — plausible, needs runtime test	transports.go:166,305-317; go-sdk streamable.go:620-624
U5	Refines finding #3 above: local sessions skipping Validate also means sliding TTL stops sliding for list-only traffic (mcp-go's per-request Validate did GETEX); tools/call/resources/read stay protected via the validating cache, but tools/list/ping/prompts serve terminated sessions.	Degraded (detail)	transports.go:216-219 vs mcp-go streamable_http.go:508,930; pkg/cache/validating_cache.go:129-146
U6	normalizeObjectSchema strips valid non-standard input schemas — any schema that isn't a map with top-level "type":"object" (type omitted, $ref, oneOf, boolean schema) is replaced by bare {"type":"object"}; properties/required silently vanish from tools/list. mcp-go passed RawInputSchema through verbatim.	Degraded	server.go:527-546
U7	Refines finding #4 above: the 401 string-matching also produces false positives — backend JSON-RPC tool errors whose text contains "401"/"unauthorized" get wrapped as auth errors, spuriously engaging vMCP's auth-aware health handling; and ErrLegacySSEServer no longer fires for 400/403/404-on-initialize (mcp-go: any 4xx except 401).	Degraded (detail)	errors.go:66-95
U8	Client-synthesized notifications are method-only — params dropped (moot today given 1a/1b, but must be fixed together with them).	Degraded	client.go:405-415
U9	Forward-compat trap, no current victim: the dispatch middleware fires before-hooks with empty request objects (&mcp.CallToolRequest{} — no tool name/args). vMCP's hooks only use ctx today; any future hook reading the request breaks silently.	Latent	server.go:403-412

Also independently re-confirmed as kept: per-session tool projection/isolation mechanism (per-session go-sdk Server, live SetSessionTools reconciliation, cross-pod lazy injection), elicitation adapter session correlation, DELETE→Terminate, identity present at CreateSession.

Additional work items

• U1. Map capability flags to go-sdk ServerOptions (or register-and-sync before the initialize result is produced) so vMCP advertises tools/resources capabilities. Merge blocker.
• U3. Key the pending-request-context bridge per request (e.g. per-message ID), not per session — or refuse fallback for identity-bearing values. Merge blocker (security).
• U2. Plumb the preset backend session ID into initialize (resume-style init or header injection) so hint-honoring backends resume sessions.
• U4. Decide elicitation delivery under JSONResponse mode (consider JSONResponse=false, or document the GET-stream requirement); make rehydrated-session behavior (capability seeding, response mode) consistent with the origin pod; fail fast on non-supporting clients.
• U5. Call Validate for local sessions too (extends work item 3 above) — restores per-request liveness + sliding TTL.
• U6. Normalize only nil/empty input schemas; pass everything else through verbatim.
• U7. Constrain 401 mapping to transport-level errors (don't string-match JSON-RPC tool error text); restore mcp-go's any-4xx-on-initialize legacy-SSE classification or update vMCP's consumer.
• U8. Carry notification params in the client bridge (with 1a).
• U9. Populate before-hook request objects (method + params) or document the limitation loudly.

The PR body's caveat list should also be rewritten: caveat 1 is understated (nothing survives the bridge end-to-end), caveat 3 is stale (mostly wired; the real gap is local-session Validate).

[JAORMX]

Fix-path corrections after SDK source verification (v1.6.1 + v1.7.0-pre.1)

Cross-checked both go-sdk versions' source directly. Confirmed: nothing newer than v1.7.0-pre.1 exists, and upgrading fixes none of the findings — every fix lands in this shim. Three corrections to the work items above:

1. Heartbeat (item 2 / U5) is a one-line wiring fix, not SSE-comment injection. go-sdk v1.6.1 already has server-side keep-alive: ServerOptions.KeepAlive time.Duration (mcp/server.go:81, started per-session at :1037-1038). The shim should wire WithHeartbeatInterval → ServerOptions.KeepAlive. (v1.7 adds KeepAliveFailureThreshold; not needed for parity.) Discard the ResponseWriter-wrapper approach.

2. U1 (capability advertisement) fix knob confirmed in v1.6.1: ServerOptions.HasTools / HasResources (mcp/server.go:126,131) are consulted when building the initialize capabilities (:573-587). Map WithToolCapabilities/WithResourceCapabilities onto them — no upgrade, no re-architecture.

3. Item 4 (401 mapping) correction: OAuthHandler is NOT an error-classification hook — it's a token-refresh/authorize flow (improved in v1.7 #917). go-sdk still surfaces non-2xx as http.StatusText strings in both versions (streamable.go:2465-2479 in v1.7.0-pre.1), so the shim's string-matching remains necessary. Rescope item 4 to: constrain matching to transport-level errors (fix the U7 false positives on tool-error text), restore any-4xx-on-initialize legacy-SSE classification, and keep the upstream ask for typed status errors.

Upstream asks — updated list (all verified absent in v1.7.0-pre.1)

• Public generic notification sender on ServerSession (only typed NotifyProgress/Log exist — blocks true list_changed passthrough).
• Preset session ID on StreamableClientTransport (no such field in any version — blocks U2 session-hint replay; the shim cannot fix this alone).
• Per-request session Validate/Terminate hooks (shim mitigates by validating in its own HTTP layer meanwhile).
• Typed HTTP-status errors from transports.
• Per-request context propagation to stateful session handlers (U3 root cause; shim mitigates by keying its bridge per-request).