Make forwarding tests' Legacy dependency explicit

The server->client forwarding integration tests (mid-call elicitation,
sampling, progress, logging) exercise a surface that exists only on a
Legacy (2025-11-25) session: the 2026-07-28 revision removed
server-initiated requests, replacing them with client-polled multi-round
retrieval (SEP-2322), and SEP-2577 deprecates sampling and logging
outright. Today these tests land on Legacy only incidentally, because the
Modern dispatch kill-switch (#5959) rejects the go-sdk client's
Modern-first probe; once the switch is removed (#6033) the client
negotiates Modern and all of them fail at connect.

Pin the downstream test clients to Legacy explicitly via a transport-level
RoundTripper that answers server/discover with the same -32022 rejection
the kill-switch produces (mcpcompat cannot pin a protocol version, #5911),
and pin the Modern-client contract for the same eliciting backend in a new
integration test: an explicit JSON-RPC error naming the refused request,
never a hang, a fabricated success, or an input_required envelope. Document
the client-edge limitation and the intended future MRTR shape (#5743) in
the vMCP architecture doc.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GvBj7nNWqDQ3rKYNeY6aam

Author: JAORMX

docs/arch/10-virtual-mcp-architecture.md

@@ -289,6 +289,68 @@ multi-round tool retrieval (MRTR), so the fix is shaped MRTR-first rather than b
 extending the SSE standalone-stream model — see the epic (#5743) and the
 mid-call forwarding section below for the Legacy behaviour this contrasts with.
 
+### Limitation: elicitation and sampling are unavailable to Modern clients
+
+The client edge mirrors the backend edge. The Modern dispatcher
+(`pkg/vmcp/server`'s `dispatchModern`) is single-shot: every result it builds is
+`resultType: "complete"`, and it never emits `"input_required"` — MRTR
+(SEP-2322) is unimplemented on this edge too. When a backend tool issues a
+mid-call server-initiated request during a **Modern** client's `tools/call`,
+there is no client session to forward it to, so the call fails with an explicit
+`-32603` whose message names the refused request (pinned by
+`TestIntegration_Modern_RealBackend_ElicitingToolFailsCleanly`). This is a
+deliberate honest-unsupported error, not a gap left by accident:
+
+- The 2026-07-28 revision **removed** server-initiated requests; go-sdk's
+  `ServerSession.assertServerInitiatedRequestAllowed` refuses
+  elicitation/sampling/roots purely by negotiated protocol version, so no
+  capability negotiation can restore the Legacy forwarding model for Modern
+  clients.
+- A server that never returns `input_required` is fully SEP-2575-conformant:
+  the per-request `clientCapabilities` a client declares are an offer the
+  server may use, not an obligation.
+- SEP-2577 deprecates sampling (and logging and roots) outright as of
+  2026-07-28, with direct LLM-provider integration as the sanctioned
+  replacement — so elicitation is the only durable consumer a future MRTR
+  implementation would serve.
+
+Legacy clients keep the full mid-call forwarding behaviour unchanged; the
+forwarding integration tests pin their downstream clients to Legacy explicitly
+(`legacyPinningRoundTripper` in `pkg/vmcp/server`) because that surface exists
+only on a Legacy session.
+
+**Bridging was considered, costed, and rejected — this is a design position,
+not a backlog item.** Serving MRTR to Modern clients on top of a *Legacy*
+backend would require parking the live, mid-flight backend call server-side
+(the blocked goroutine and its open session cannot be serialized into the
+opaque `requestState` the SEP designed for handler re-invocation) and keying
+the resume on an unguessable token — per-round server state with TTL/eviction,
+identity binding on a token that becomes a capability to resume someone else's
+in-flight call, and replica affinity with no `Mcp-Session-Id` to route on. That
+is a session in disguise: exactly the construct the 2026-07-28 revision
+removed. The spec's own sanctioned path for genuinely stateful
+`input_required` work is the **Tasks** extension (SEP-1686: `tools/call`
+returns a `taskId`; the client polls `tasks/get`/`tasks/result` and answers via
+`tasks/input_response`) — if Modern-client elicitation over Legacy backends is
+ever truly demanded, that is the machinery to reach for, not parked
+`tools/call`.
+
+The coherent future MRTR shape for a re-aggregating gateway is
+**Modern-client ↔ Modern-backend pass-through** — relay a Modern backend's
+`inputRequests`/`requestState` to the client and the client's
+`inputResponses` back, genuinely stateless at vMCP. It requires the egress
+half first (today a Modern backend's `input_required` surfaces as
+`errModernInputRequired`, the seam left in `pkg/vmcp/client`), and by the time
+Modern backends exist to relay from, SEP-2577's deprecations make elicitation
+its only durable consumer; see #5743.
+
+Progress and log notifications toward Modern clients are a separate concern
+from MRTR: they remain spec-legal as request-scoped notifications on the
+POST-initiated SSE response stream (SEP-2260 requires messages on that stream
+to relate to the originating request; `progressToken` is unchanged), which the
+single-shot dispatcher does not produce today — a vMCP streaming-dispatch gap,
+not a spec absence.
+
 ## Served MCP Capabilities
 
 Beyond tools, vMCP aggregates and serves the full complement of MCP capabilities. Every served capability flows through the domain **core** (`pkg/vmcp/core`), so the same admission decision that filters `tools/list` also gates reads, gets, and completions.

pkg/vmcp/server/forwarding_realbackend_integration_test.go

@@ -4,7 +4,10 @@
 package server_test
 
 import (
+	"bytes"
 	"context"
+	"encoding/json"
+	"io"
 	"net/http"
 	"net/http/httptest"
 	"sync/atomic"
@@ -18,12 +21,18 @@ import (
 	"github.com/stacklok/toolhive-core/mcpcompat/client/transport"
 	mcpmcp "github.com/stacklok/toolhive-core/mcpcompat/mcp"
 	mcpserver "github.com/stacklok/toolhive-core/mcpcompat/server"
+	mcpparser "github.com/stacklok/toolhive/pkg/mcp"
 )
 
 // Forwarding integration fixtures. These exercise the server->client forwarding
 // cluster end-to-end: a real in-process backend, mid tools/call, drives
 // elicitation/sampling/progress/logging back at its caller; vMCP must relay that
-// traffic to the real downstream client on the same session.
+// traffic to the real downstream client on the same session. That session is
+// necessarily Legacy (2025-11-25): the Modern revision removed server-initiated
+// requests, so the downstream clients here are explicitly pinned to Legacy —
+// see legacyPinningRoundTripper. The Modern-client behavior for the same
+// eliciting backend is asserted separately in
+// TestIntegration_Modern_RealBackend_ElicitingToolFailsCleanly.
 const (
 	fwdElicitTool   = "elicit_tool"
 	fwdSampleTool   = "sample_tool"
@@ -130,9 +139,73 @@ func startForwardingBackend(t *testing.T) string {
 	return ts.URL + "/mcp"
 }
 
+// legacyPinningRoundTripper pins a downstream mcpcompat client to the Legacy
+// (2025-11-25) revision by answering its Modern-first server/discover probe
+// with the same HTTP 400 / JSON-RPC -32022 UnsupportedProtocolVersionError
+// body vMCP's kill-switch produces (reusing the production
+// mcpparser.ClassificationErrorResponse builder), which drives go-sdk's
+// Connect down its documented fall-back-to-Legacy-initialize path. Every
+// other request passes through to base untouched.
+//
+// WHY PIN: these fixtures assert the Legacy-only server-initiated surface —
+// mid-call elicitation/sampling requests and progress/logging notifications
+// relayed over a live session. The 2026-07-28 revision removes server-
+// initiated requests entirely (go-sdk's assertServerInitiatedRequestAllowed
+// refuses them by protocol version; the replacement is client-polled
+// multi-round retrieval, SEP-2322) and SEP-2577 deprecates sampling and
+// logging outright. While the Modern dispatch kill-switch (#5959) is on, vMCP
+// itself rejects the probe and these clients land on Legacy incidentally;
+// once it is removed (#6033) the go-sdk-based client would negotiate Modern
+// and this surface would vanish mid-test — failing at connect on
+// subscriptions/listen, not at the behavior under test. Pinning makes the
+// tests' Legacy dependency explicit instead of incidental.
+//
+// The pin lives in the transport because mcpcompat documents it cannot set a
+// protocol version (go-sdk's ClientSessionOptions.protocolVersion is
+// unexported — see the LIMITATION note in mcpcompat/client and #5911).
+// Replace this with a real client option if #5911 lands.
+//
+// LOAD-BEARING after #6033: once the kill-switch is gone, this RoundTripper
+// is the ONLY thing keeping these downstream clients on Legacy. It is not
+// leftover kill-switch scaffolding — deleting it silently flips every test
+// in this file to Modern and voids what they assert.
+type legacyPinningRoundTripper struct{ base http.RoundTripper }
+
+func (rt *legacyPinningRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
+	if req.Method != http.MethodPost || req.Body == nil {
+		return rt.base.RoundTrip(req)
+	}
+	body, err := io.ReadAll(req.Body)
+	_ = req.Body.Close()
+	if err != nil {
+		return nil, err
+	}
+	req.Body = io.NopCloser(bytes.NewReader(body))
+	var probe struct {
+		ID     any    `json:"id"`
+		Method string `json:"method"`
+	}
+	if json.Unmarshal(body, &probe) == nil && probe.Method == "server/discover" {
+		return mcpparser.ClassificationErrorResponse(req, probe.ID, &mcpparser.UnsupportedVersionError{
+			Requested: mcpparser.MCPVersionModern,
+			Supported: []string{mcpparser.MCPVersionLegacy},
+		}), nil
+	}
+	return rt.base.RoundTrip(req)
+}
+
+// legacyPinnedHTTPClient returns an *http.Client for
+// transport.WithHTTPBasicClient that pins the mcpcompat client to Legacy —
+// see legacyPinningRoundTripper.
+func legacyPinnedHTTPClient() *http.Client {
+	return &http.Client{Transport: &legacyPinningRoundTripper{base: http.DefaultTransport}}
+}
+
 // downstreamClient builds a real mcpcompat client against the vMCP endpoint,
 // wired for server->client traffic (elicitation/sampling handlers, continuous
 // listening) and collecting forwarded notifications on the returned channel.
+// It is pinned to the Legacy revision (see legacyPinningRoundTripper): the
+// forwarded traffic it collects exists only on a Legacy session.
 type downstreamClient struct {
 	c        *client.Client
 	notifCh  chan mcpmcp.JSONRPCNotification
@@ -185,7 +258,10 @@ func newDownstreamClient(ctx context.Context, t *testing.T, vmcpURL string, with
 
 	c, err := client.NewStreamableHttpClientWithOpts(
 		vmcpURL,
-		[]transport.StreamableHTTPCOption{transport.WithContinuousListening()},
+		[]transport.StreamableHTTPCOption{
+			transport.WithContinuousListening(),
+			transport.WithHTTPBasicClient(legacyPinnedHTTPClient()),
+		},
 		clientOpts,
 	)
 	require.NoError(t, err)
@@ -235,6 +311,11 @@ func (dc *downstreamClient) waitNotification(ctx context.Context, t *testing.T,
 // TestForwarding_Elicitation_RealBackend verifies a backend's mid-call
 // elicitation/create is relayed to the downstream client and its response
 // carried back into the tool result.
+//
+// Legacy-pinned: a server-initiated elicitation/create toward the client does
+// not exist on Modern (2026-07-28) — SEP-2322 replaces it with client-polled
+// inputRequests, which vMCP deliberately does not serve (see the "unavailable
+// to Modern clients" limitation in docs/arch/10-virtual-mcp-architecture.md).
 func TestForwarding_Elicitation_RealBackend(t *testing.T) {
 	t.Parallel()
 	ctx, cancel := context.WithTimeout(t.Context(), forwardingRealBackendTimeout)
@@ -265,6 +346,11 @@ func TestForwarding_Elicitation_RealBackend(t *testing.T) {
 // TestForwarding_Sampling_RealBackend verifies a backend's mid-call
 // sampling/createMessage is relayed to the downstream client and the sampled
 // message carried back into the tool result.
+//
+// Legacy-pinned: like elicitation, server-initiated sampling does not exist on
+// Modern (SEP-2322) — and SEP-2577 additionally deprecates the sampling
+// feature itself as of 2026-07-28 (sanctioned replacement: direct LLM-provider
+// integration), so this surface is Legacy-only by spec, not by omission.
 func TestForwarding_Sampling_RealBackend(t *testing.T) {
 	t.Parallel()
 	ctx, cancel := context.WithTimeout(t.Context(), forwardingRealBackendTimeout)
@@ -288,6 +374,17 @@ func TestForwarding_Sampling_RealBackend(t *testing.T) {
 // TestForwarding_Progress_RealBackend verifies a backend's mid-call
 // notifications/progress is relayed to the downstream client, arriving before
 // the tool result is read.
+//
+// Legacy-pinned — but NOT because Modern lacks a progress channel. It does
+// not: on Modern, progress remains spec-legal as a request-scoped
+// notification riding the POST-initiated SSE response stream (SEP-2260
+// tightened exactly that channel; progressToken is unchanged in the draft
+// schema). What is missing is on vMCP's side: dispatchModern is single-shot —
+// writeModernResult emits one JSON body and cannot stream — so nothing riding
+// the per-request stream is deliverable to a Modern client today. That is a
+// vMCP "streaming Modern dispatch" gap (future work), distinct from both MRTR
+// and subscriptions/listen (whose subscribable set is fixed at four
+// list-changed/subscription types and excludes progress).
 func TestForwarding_Progress_RealBackend(t *testing.T) {
 	t.Parallel()
 	ctx, cancel := context.WithTimeout(t.Context(), forwardingRealBackendTimeout)
@@ -312,6 +409,22 @@ func TestForwarding_Progress_RealBackend(t *testing.T) {
 // TestForwarding_Logging_RealBackend verifies that vMCP requests debug logging
 // from the backend (so it emits) and relays the backend's notifications/message
 // to the downstream client, which has itself set a logging level.
+//
+// Legacy-pinned, for three stacked reasons — record them so this is not
+// re-litigated as a vMCP bug:
+//  1. Upstream go-sdk defect: SetLoggingLevel omits injectRequestMeta
+//     (client.go:1303 in v1.7.0-pre.3; every other Modern-aware method
+//     injects), so a Modern logging/setLevel carries the MCP-Protocol-Version
+//     header but no _meta.protocolVersion. vMCP's ClassifyRevision CORRECTLY
+//     rejects that with -32020; accepting the malformed request to make this
+//     test pass would be worse than the failure. Filed upstream separately.
+//  2. Even with (1) fixed, Modern log delivery is gated on the per-request
+//     logLevel _meta key (SEP-2575: absent means the server must not send log
+//     notifications for that request) and rides the same per-request SSE
+//     response stream the single-shot dispatcher cannot produce — the same
+//     streaming gap as TestForwarding_Progress_RealBackend.
+//  3. SEP-2577 deprecates the logging feature itself as of 2026-07-28
+//     (sanctioned replacement: stderr / OpenTelemetry).
 func TestForwarding_Logging_RealBackend(t *testing.T) {
 	t.Parallel()
 	ctx, cancel := context.WithTimeout(t.Context(), forwardingRealBackendTimeout)
@@ -340,6 +453,14 @@ func TestForwarding_Logging_RealBackend(t *testing.T) {
 // when the downstream client did not advertise sampling, the backend's
 // sampling request fails cleanly (a failed tools/call) rather than hanging until
 // the deadline.
+//
+// Legacy-pinned even though it happens to pass on Modern: capability-gated
+// failure on a live session only exists on Legacy. On Modern the same call
+// fails with the sessionless -32603 REGARDLESS of what the client advertises
+// (withHandlers makes no difference), so the lenient assertion here would be
+// satisfied for a reason unrelated to the gating this test exists to
+// exercise. The pin keeps it testing what its name says. (Verified against a
+// working subscriptions/listen build: unpinned, this test passes vacuously.)
 func TestForwarding_Sampling_NoDownstreamCapability(t *testing.T) {
 	t.Parallel()
 	ctx, cancel := context.WithTimeout(t.Context(), forwardingRealBackendTimeout)
@@ -365,6 +486,7 @@ func TestForwarding_Sampling_NoDownstreamCapability(t *testing.T) {
 // TestForwarding_Sampling_NoDownstreamCapability: when the downstream client did
 // not advertise elicitation, the backend's mid-call elicitation/create fails
 // cleanly (a failed tools/call) rather than hanging until the deadline.
+// Legacy-pinned for the same vacuous-pass reason as its sampling twin above.
 func TestForwarding_Elicitation_NoDownstreamCapability(t *testing.T) {
 	t.Parallel()
 	ctx, cancel := context.WithTimeout(t.Context(), forwardingRealBackendTimeout)
@@ -397,14 +519,18 @@ type samplingClient struct {
 // newSamplingClient connects a downstream client to vmcpURL whose sampling
 // handler always answers with the given summary and model (so the tool result
 // distinguishes which client's handler served the request) and increments a
-// per-client counter.
+// per-client counter. Pinned to Legacy like newDownstreamClient — see
+// legacyPinningRoundTripper.
 func newSamplingClient(ctx context.Context, t *testing.T, vmcpURL, summary, model string) *samplingClient {
 	t.Helper()
 
 	sc := &samplingClient{}
 	c, err := client.NewStreamableHttpClientWithOpts(
 		vmcpURL,
-		[]transport.StreamableHTTPCOption{transport.WithContinuousListening()},
+		[]transport.StreamableHTTPCOption{
+			transport.WithContinuousListening(),
+			transport.WithHTTPBasicClient(legacyPinnedHTTPClient()),
+		},
 		[]client.ClientOption{
 			client.WithSamplingHandler(client.SamplingHandlerFunc(
 				func(_ context.Context, _ mcpmcp.CreateMessageRequest) (*mcpmcp.CreateMessageResult, error) {
@@ -448,6 +574,10 @@ func newSamplingClient(ctx context.Context, t *testing.T, vmcpURL, summary, mode
 // call's sampling request were relayed to B's session, A's tool result would show
 // "summary-B" (mismatching the "summary-A" assertion) and the handler counters
 // would be lopsided (A=0, B=2 instead of 1/1) — either check trips.
+//
+// Legacy-pinned for the same reasons as TestForwarding_Sampling_RealBackend:
+// per-session routing of a server-initiated request presupposes sessions,
+// which Modern removed along with the requests themselves.
 func TestForwarding_Sampling_RealBackend_SessionIsolation(t *testing.T) {
 	t.Parallel()
 	ctx, cancel := context.WithTimeout(t.Context(), forwardingRealBackendTimeout)

pkg/vmcp/server/modern_realbackend_integration_test.go

@@ -306,6 +306,55 @@ func TestIntegration_Modern_RealBackend_UnknownMethod(t *testing.T) {
 	assert.EqualValues(t, -32601, errObj["code"])
 }
 
+// TestIntegration_Modern_RealBackend_ElicitingToolFailsCleanly pins the
+// Modern-client behavior for a backend tool that issues a mid-call
+// server-initiated request (elicitation/create, sampling/createMessage): the
+// call MUST resolve promptly to an explicit JSON-RPC error naming the refused
+// request — never a hang, never a fabricated success, and never a resultType
+// "input_required" envelope, which this dispatcher does not emit (client-polled
+// multi-round retrieval, SEP-2322, is unimplemented; modernResultTypeComplete
+// is the only resultType modern_envelope.go builds).
+//
+// This is the honest-unsupported contract for the surface the 2026-07-28
+// revision removed: server-initiated requests need a live session, Modern
+// requests have none by design, and SEP-2577 additionally deprecates sampling
+// outright. The Legacy-session behavior for the same backend tools is covered
+// by the TestForwarding_* fixtures, whose downstream clients pin Legacy
+// explicitly (see legacyPinningRoundTripper).
+func TestIntegration_Modern_RealBackend_ElicitingToolFailsCleanly(t *testing.T) {
+	t.Parallel()
+
+	backendURL := startForwardingBackend(t)
+	ts := newRealModernTestServer(t, backendURL)
+
+	tests := []struct {
+		name string
+		tool string
+		want string // substring naming the refused server-initiated request
+	}{
+		{name: "elicitation", tool: fwdElicitTool, want: "elicitation/create"},
+		{name: "sampling", tool: fwdSampleTool, want: "sampling/createMessage"},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			resp, decoded := postModern(t, ts.URL, "tools/call", map[string]any{"name": tc.tool}, 1, tc.tool)
+			defer resp.Body.Close()
+
+			// A -32603 rides HTTP 200 per writeModernError's status mapping: the
+			// request was accepted and processed; the failure is application-level.
+			require.Equal(t, http.StatusOK, resp.StatusCode, "decoded: %+v", decoded)
+			require.NotContains(t, decoded, "result",
+				"must not fabricate a success or an input_required envelope: %+v", decoded)
+			errObj, ok := decoded["error"].(map[string]any)
+			require.True(t, ok, "decoded: %+v", decoded)
+			assert.EqualValues(t, -32603, errObj["code"])
+			assert.Contains(t, errObj["message"], tc.want,
+				"the error must name the refused server-initiated request")
+		})
+	}
+}
+
 // TestIntegration_Modern_RealBackend_MalformedArguments verifies a
 // syntactically valid tools/call whose "arguments" is present but not a JSON
 // object is rejected with 400 + JSON-RPC -32602, per hasNonObjectArguments'