Serve MCP 2026-07-28 Modern stateless requests through vMCP

[jhrozek]

Summary

ToolHive is adding support for the MCP 2026-07-28 ("Modern") stateless revision. The transport proxies already classify-and-forward Modern requests (#5884); this change makes the vMCP server serve them itself — bypassing the SDK Serve/session layer and dispatching straight to the already-stateless vMCP core, so a handshake-less client can talk to a virtual MCP server.

• Hand-rolled Modern wire envelope (resultType, _meta serverInfo, Cacheable with cacheScope:"private" for identity-scoped results) — the imported go-sdk v1.6.1 has no Modern shapes, so the envelope is reproduced against v1.7.0-pre.3 and checked against its conformance fixtures.
• classifyingHandler routes well-formed Modern requests to the hand-rolled dispatcher; Legacy and malformed-Modern behavior is unchanged.
• Serves tools/resources/prompts list + call/read/get, server/discover (post-admission capability flags via core.Discover), ping, and completion/complete; notifications → 202, unimplemented → 404/-32601, malformed params → 400/-32602.
• Security-critical: because it bypasses the SDK server, it re-homes that server's pre-dispatch authorization gate — Check* before dispatch and a dispatch-time ErrAuthorizationFailed both map to HTTP 403 + the matching deny message (so a denial audits as denied, not a 200 tool-error or -32603). Cedar itself fails closed (→ 403); the only "fail-open" is a non-authorization plumbing error from the pre-dispatch CheckToolCall (the sole gated verb that re-aggregates), which admits the request — but CallTool independently re-derives the decision before contacting any backend, so this never yields an unauthorized backend call. Successful backend calls label the audit backend_name.
• server/discover is allow-listed on the single-server authz path (parity with initialize).

Closes #5910

Type of change

• New feature

Test plan

• Unit tests (task test)
• Linting (task lint-fix)
• Manual testing (describe below)

Integration tests (modern_realbackend_integration_test.go) drive real Modern JSON-RPC-over-HTTP through the fully-assembled server into a real core + real backend, asserting the wire bytes: no Mcp-Session-Id on Modern, envelope shapes, 202/404/400, server/discover flags through the admission seam, denial → 403. go-sdk v1.7 could not be imported (it would force an MVS bump of the whole module), so a hand-rolled raw HTTP client is used; independent-client + upstream-conformance validation for Modern is deferred to the #5837 harness.

API Compatibility

• This PR does not break the v1beta1 API (no operator/CRD surface is touched).

Changes

Four commits:

1. Add core.Discover and result backend attribution — single-pass, post-admission capability flags for server/discover (one aggregatedView, same admission filters as the List* verbs), plus an audit-only BackendID (json:"-") on the call/read/get results.
2. Serve MCP 2026-07-28 Modern stateless requests through vMCP — the envelope, the dispatcher, the re-homed authz gate, the classifyingHandler wiring, and discover/completion/ping serving.
3. Allow-list server/discover on the single-server path — pkg/authz.
4. Add Modern stateless integration tests.

Does this introduce a user-facing change?

Yes — a vMCP server now serves MCP 2026-07-28 ("Modern") stateless requests directly (no initialize handshake), in addition to the existing Legacy (2025-11-25) path. Modern dispatch is unconditional for well-formed Modern requests.

Special notes for reviewers

• Size / split. This is ~3k LOC across ~17 non-generated files — well over the repo's ≤400-LOC / ≤10-file norm. It was planned as two PRs: PR(a) = the envelope + dispatcher + wiring + integration tests, PR(b) = server/discover + authz allow-list + completion/complete. Opened as a single PR per request; happy to split for review if preferred.
• Kill-switch removed (deliberate deviation from the issue). Serve MCP 2026-07-28 stateless requests through vMCP (server-side Modern path) #5910 specified a default-off startup kill-switch. It was dropped after review established zero Legacy impact: ClassifyRevision routes every non-Modern request to the unchanged SDK path before dispatch, and Modern classification requires an exact MCP-Protocol-Version: 2026-07-28 header or a reserved io.modelcontextprotocol/* _meta key that no conformant Legacy client emits (initialize is force-Legacy). Routing tests cover this.
• The envelope is a durable parallel serializer, not a delete-and-repoint shim. resultType/serverInfo are set by unexported go-sdk functions inside the dispatch path this bypasses, so a future v1.7 bump will not simply delete it.
• Audit backend_name is labeled on the success path only. On a backend-call failure it is omitted (Legacy includes it because it pre-resolves the backend at session registration) — accepted, because the stateless dispatcher cannot pre-route (the backend is resolved inside the core).
• server/discover runs one backend fan-out per call (uncached on the stateless path); a cross-request per-identity capability cache is tracked separately (Support MCP caching metadata (ttlMs/cacheScope) in vMCP #5761).

🤖 Generated with Claude Code

[JAORMX]

Panel review (reviewed at 0016ed50)

I ran this through a multi-lens review — MCP wire-format/JSON-RPC conformance, authorization/security, Go correctness/concurrency, and vMCP architectural fit + test coverage. Overall this is a strong, unusually well-documented change: the re-homed authz gate is substantially correct, the concurrency story holds (the stateless dispatcher genuinely has no shared mutable state, so no keyedMutex needed), response-writer discipline is clean (marshal-before-write, write-once, return after every error write), and core.Discover's single-fan-out reuse of the existing admission filters is a nice consolidation. No blocking correctness or security defects found — in particular, no authorization bypass: every backend-reaching verb is gated, and a dispatch-time ErrAuthorizationFailed reliably maps to 403 + deny message (audited as denied, tested first in writeModernDispatchError).

A few should-fixes below, mostly around strict spec conformance and one test gap. None are merge-blockers on their own, but I'd like to see #1 and #2 addressed (or explicitly deferred with a tracking issue) before I approve.

⚠️ CI: the one red check — TestStandaloneSSE_ListChangedRefiltersThroughExistingMiddleware in pkg/transport/proxy/streamable — is in a package this PR does not touch (all changes are pkg/authz + pkg/vmcp). Looks unrelated/flaky; worth a re-run to confirm it's green before merge.

Should-fix

1. Spec MUST: a Modern POST that omits the MCP-Protocol-Version header is accepted instead of rejected. (classification.go:38-55, pkg/mcp/revision.go:283-299)
Per the draft Streamable HTTP spec, every POST to the MCP endpoint MUST carry MCP-Protocol-Version; a missing header is a validation failure that MUST return 400 + -32020. Today a body with a reserved _meta key + valid protocolVersion + clientCapabilities but no header classifies (RevisionModern, nil) and dispatches → 200. Relatedly, a reserved-key-only body with no version + no header returns -32602 where the spec wants -32020 (MissingModernMetadataError). Your own TODO at revision.go:292-297 calls this out exactly — and it's now resolvable, since classifyingHandler does have HTTP header context and can enforce header presence for Modern before dispatch.

2. No assembled-server test of the authz-denial path — the very reason the gate is re-homed. (session_management_realbackend_integration_test.go:84-97)
newRealTestHandler builds the server with no Authz config, so authzGateEnabled is false in every modern_realbackend_integration_test.go case. The gate is thoroughly unit-tested (TestDispatchModern_AuthzGate covers pre-dispatch 403, TOCTOU 403, fail-open, non-authz -32603, gate-off), but the middleware-ordering assumption you rely on — "audit is outer, so a dispatcher 403 audits as denied" — is never exercised end-to-end. One real-server test with authz enabled asserting a Cedar-denied Modern tools/call → 403 and a denied audit outcome would lock in the security-critical invariant.

3. -32603 returns err.Error() verbatim to the client. (modern_dispatch.go:125,130,141,152,163,192,426)
Two reviewers independently flagged this. The wrapped chains ("capability aggregation failed: %w", "routing tool %q: %w") can carry internal backend IDs / plumbing detail, which security.md says not to leak. I see your comment (modern_dispatch.go:415-420) arguing this is deliberate parity with the SDK/legacy path (conversion.ErrorToToolResult, serve_handlers.go). That's fair for the call/read/get branches — but could you confirm the legacy tools/list path exposed the same raw text? If not, the list-verb -32603 branches (125/130/141/152/163/192) are newly exposing it, and a generic message (with err logged server-side) would be safer there.

Discussion / judgment

4. Kill-switch removal & rollback story. The "zero Legacy impact" justification is correct but answers a different risk than the one #5910's flag mitigated. Legacy is genuinely untouched. The risk the flag covered is that Modern clients get a hand-rolled envelope mirroring go-sdk v1.7.0-pre.3 — a version this module does not import (it's on v1.6.1), so there's no compile-time check the shapes match and the envelope tests assert against hand-written expected JSON, not real SDK bytes. With the flag, disabling Modern let those requests fall through to the SDK's version downgrade — a strictly safer degraded mode than serving a possibly-wrong pre-release envelope, and it's a runtime lever rather than revert-and-redeploy. I'd lean toward restoring a default-off switch for a hand-rolled pre-release protocol, or at minimum getting explicit maintainer sign-off recorded here that unconditional serving is accepted until the #5837 conformance harness lands.

5. PR size / split. ~3.2k LOC / 20 files is well over the repo norm. The proposed (a) envelope+dispatcher+wiring+tests / (b) discover+authz+completion split is sensible and matches your commit boundaries — I'd take it for reviewability. (Note: PR(a) would need the server/discover + completion/complete switch cases stubbed to -32601 so it doesn't advertise methods it can't serve.)

Nits (non-blocking)

• PR description wording: "fail-open on infra errors" overstates the exposure. Cedar runs in-process and fails closed (→ 403); the only fail-open trigger is a non-authz plumbing error from CheckToolCall, and CallTool independently re-aggregates and fails -32603 before reaching a backend — so fail-open never yields an unauthorized backend call. Worth rewording so a future reader doesn't "fix" it into a real hole. Also: only tools/call can fail open (CheckResourceRead/CheckPromptGet don't aggregate), yet gateDenied's comment reads as if all three do.
• ping omits resultType (modern_dispatch.go:99-107). Draft schema marks Result.resultType a MUST for a 2026-07-28 server; a strict conformance suite would flag the bare {}. Your SDK-parity rationale is documented and real clients treat absent as "complete", so likely fine — flagging so it's a conscious call.
• Gate coverage is duplicated across call_gate.go and modern_dispatch.go (two method→gate switches). core.Check* guarantees the decision can't diverge, but coverage could (a verb gated on one path, forgotten on the other). A single method→gate table driving both would remove the drift risk — good follow-up.
• Dead nil-guards: newModernCallToolResult/ReadResource/GetPrompt guard result == nil, but callers deref result.BackendID first (modern_dispatch.go:227,250,282), so a nil would panic upstream — the guards are unreachable. Either drop them or make the deref defensive.
• Explicit "id": null decodes to parsed.ID == nil → treated as a notification (202). Spec forbids null id, so low-risk, but worth confirming the parser distinguishes absent from explicit-null.

Nice work overall — the doc comments made this genuinely reviewable at this size. I'll keep watching and approve once the header-validation (#1) and denial-path test (#2) are sorted (or explicitly punted with issues).

_{🤖 Panel review assisted by Claude Code}

[JAORMX]

@jhrozek I went ahead and pushed two commits addressing the two should-fixes I flagged, to save you a round-trip — please review/squash/drop as you see fit.

1e6672ae — Reject header-less Modern requests with -32020 (should-fix #1)
Fixes the substantive half of the finding: a body that classifies Modern via its reserved _meta keys but omits the mandatory MCP-Protocol-Version header was dispatched and answered 200; it now returns 400/-32020, per the draft Streamable HTTP "Server Validation" rules. I kept it surgical and in-layer — the check lives in classifyingHandler and fires only on the rev == Modern && err == nil && header == "" path (the one that was wrongly accepted), so the existing -32602/-32022/-32020 rejection codes are untouched and no existing test changes. ClassifyRevision stays transport-agnostic; its TODO for generalizing this into the shared classifier (which would also cover the streamable/transparent proxies via transport context) is intentionally left in place as follow-up, since changing the shared signature would pull two other components into this PR.

I did not re-code the minor S2 nuance (reserved-key-only + no version + no header still returns -32602 rather than -32020) — both are 400 rejections, and touching it would require special-casing MissingModernMetadataError. Happy to add it if you'd rather close it fully.

c661d9ae — Test Modern authz denial through assembled server (should-fix #2)
Adds the Modern counterpart of TestIntegration_CedarAuthzDenialIsAudited: a policy-denied Modern tools/call must return 403 + JSON-RPC 403 and audit as denied through the fully assembled server (audit → parsing → classification → dispatchModern). This locks in the middleware-ordering invariant the re-homed gate depends on — previously only covered by dispatchModern unit tests. Reuses your buildCedarAuthzServer + postModern helpers; the shared audit-log helper lost its now-constant eventType param to satisfy unparam.

Verified locally: pkg/vmcp/server, pkg/mcp, pkg/authz pass with -race, and task lint-fix is clean. Watching CI.

On the discussion items (verbatim -32603 error text #3, kill-switch/rollback #4, PR split #5): I left those alone — they're design calls for you, not mechanical fixes. Your documented SDK-parity rationale for #3 stands; the only open question there was whether the legacy tools/list path exposed the same raw text.

_{🤖 Pushed with Claude Code}

[JAORMX]

CI note on c661d9ae: everything is green except Tests / Test Go Code, and that red is two unrelated flaky integration tests, not the pushed changes:

1. TestStandaloneSSE_ListChangedRefiltersThroughExistingMiddleware (pkg/transport/proxy/streamable) — the same expected 400, actual 200 failure that was already red on the pre-push run (0016ed50). This PR touches no code in that package.
2. TestForwarding_Progress_RealBackend (pkg/vmcp/server) — timed out waiting for notifications/progress notification (a 15s timeout in a real-backend progress-forwarding test). It's a Legacy/session test; the header-presence check I added fires only when a request classifies Modern, so it can't affect this path.

gotestfmt hides passing tests, so those two are the complete failure set — the new tests (TestClassifyingHandler's missing-header case and TestIntegration_CedarAuthzDenial_ModernPath_IsAudited) passed, alongside green Lint, Codegen, E2E Lifecycle (all 3 node versions), CodeQL, and the security scans. Locally pkg/vmcp/server, pkg/mcp, and pkg/authz pass with -race. A re-run of the Test Go Code job should clear both flakes.

_{🤖 via Claude Code}

[jhrozek]

Thanks for the thorough pass. All points addressed:

• fix(typo): corrects readme #1 / Do we want the container monitor? #2 — landed via your two commits (header-less Modern → -32020, assembled-server denial test). Thanks for saving the round-trip.
• Bump golangci/golangci-lint-action from 2f856675483cb8b9378ee77ee0beb67955aca9d7 to 4696ba8babb6127d732c3c6dde519db15edab9ea #3 (-32603 leak) — checked the Legacy side first: it never surfaces a list error to the client at all (the registration-time ListTools error is swallowed and only logged), so the raw wrapped text on the Modern list verbs was a new exposure. Genericized tools/list / resources/list / resources/templates/list / prompts/list + server/discover to a plain -32603 "internal error" with the full error logged server-side; kept tools/call / resources/read / prompts/get / completion on err.Error() per the documented SDK-parity comment.
• Implement secret store #4 (kill-switch) — agreed the real risk is the hand-rolled pre-release envelope, not Legacy, so I restored the default-off switch (TOOLHIVE_VMCP_MODERN_STATELESS; off falls through to the SDK downgrade). Filed Remove the vMCP Modern stateless dispatch kill-switch before GA #5959 (sub-issue of the epic) to remove it before GA, once Live e2e tests for dual-era stateless proxy behavior (local, k8s, CI) #5837 conformance lands or mcpcompat picks up go-sdk v1.7 so the shapes are compile-checked.
• Nits — reworded the "fail-open" wording (Cedar fails closed; only tools/call's check can admit on a non-authz plumbing error, and CallTool re-derives before any backend call), fixed the gateDenied comment to match, and dropped the unreachable nil-guards.

CI: the one red check is the TestStandaloneSSE_ListChangedRefiltersThroughExistingMiddleware streamable flake — unrelated to this diff, matches your note. Left the PR-size split as a follow-up unless you'd rather take it split now.

[JAORMX]

Rebased onto latest main + CI fix + fresh panel review

@jhrozek — heads up, I force-pushed a rebase of this branch onto current main (was based on 2da1fcbb; main is now 96eec94b, with #5965's vMCP list_changed merged since). The rebase applied cleanly, no conflicts, and go build, task lint (0 issues), and task test -race are green for the touched packages (pkg/vmcp/..., pkg/authz, pkg/mcp).

What I changed on top of your commits (one new commit)

• Fixed the Codespell CI failure — the illustrative "ture" in the kill-switch comment (serve.go) tripped codespell. Reworded it rather than adding ture to the repo-wide ignore list (which would mask a common misspelling everywhere).
• Removed 4 stray comment markers that aren't a ToolHive convention, keeping the explanatory prose.
• Fixed a stale comment in the list-dispatch helpers that referenced a nextCursor envelope field that doesn't exist (the structs carry no cursor field; omitting the optional PaginatedResult.nextCursor is spec-valid).

The previously-red TestStandaloneSSE_ListChangedRefiltersThroughExistingMiddleware is in pkg/transport/proxy/streamable (untouched here); it passes in isolation and produced no failure post-rebase — unrelated flake.

Panel review (rebased tree) — no blocking defects on any axis

Re-reviewed across four axes with independent Opus agents:

• Security / authz — CLEAN, no bypass. Every backend-reaching verb is gated pre-dispatch; fail-open is genuine defense-in-depth (CallTool/ReadResource/GetPrompt/Complete re-authorize in core_calls.go before any backend contact); TOCTOU → 403/denied verified end-to-end.
• MCP wire/JSON-RPC conformance — CLEAN. Envelope shapes verified against the 2026-07-28 draft schema.ts: resultType, Cacheable placement (incl. ListResourceTemplatesResult cacheable, CallTool/GetPrompt/Complete not), cacheScope/ttlMs, io.modelcontextprotocol/serverInfo key, server/discover, and the full error-code/HTTP-status matrix (−32020/−32022/−32601/404, 202 for notifications). Missing-header → −32020/400 confirmed fixed.
• Go correctness / concurrency — no blocking. No shared mutable state (no keyedMutex needed), writer discipline correct, the prior "dead nil-guard" concern is correctly resolved, rebase composes with Consume backend list_changed in vMCP and propagate to clients #5965.
• vMCP fit / reuse / tests — clean. No anti-patterns introduced; kill-switch keeps the path inert by default; critical paths tested (authz-denial through the assembled server, TOCTOU 403, header validation).

Non-blocking follow-ups (deliberately NOT expanded here to keep PR scope)

1. -32603 on tools/call/resources/read/prompts/get reuses err.Error() verbatim — confirmed genuine parity with the Legacy SDK path (not a regression), but worth routing both paths through the list-verb masking helper later, since it can surface upstream addressing.
2. Extract a shared vmcp.Tool → mcp.Tool helper (modernToolFromDomain vs coreSessionTools) so Legacy/Modern parity is structural, not comment-enforced.
3. A gate-coverage sync test (or shared method→gate table) across call_gate.go and modern_dispatch.go to remove drift risk.
4. ping returns bare {} (no resultType) — matches go-sdk v1.7.0-pre.3 parity; strict server-side conformance would prefer resultType:"complete".

Kill-switch removal remains tracked in #5959.

_{🤖 Rebase + panel review assisted by Claude Code}

[codecov]

Codecov Report

❌ Patch coverage is 88.72549% with 46 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.96%. Comparing base (5f6076e) to head (efb7421).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
pkg/vmcp/server/modern_dispatch.go	90.96%	9 Missing and 5 partials ⚠️
pkg/vmcp/core/core_vmcp.go	54.54%	5 Missing and 5 partials ⚠️
pkg/vmcp/server/modern_envelope.go	94.62%	5 Missing and 5 partials ⚠️
pkg/vmcp/cli/serve.go	0.00%	8 Missing ⚠️
pkg/vmcp/core/core_calls.go	73.33%	2 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5953      +/-   ##
==========================================
+ Coverage   71.88%   71.96%   +0.08%     
==========================================
  Files         715      717       +2     
  Lines       73501    73899     +398     
==========================================
+ Hits        52835    53185     +350     
- Misses      16883    16914      +31     
- Partials     3783     3800      +17     

☔ 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]

Rebased onto latest main (now includes the swagger-dedup fix #5970), so the Verify Swagger Documentation check that was red here — a pre-existing flaky-codegen artifact on main, unrelated to this PR — is resolved. Head is now efb74215; CI re-running.