mcp: fail Ping fast on 2026-07-28 sessions

[azilber]

Updates #1377. Follow-up to #1249 / #1174 / #1130, which closed the missing-_meta reports as by design because the 2026-07-28 protocol schema removes ping.

This change completes that ruling on the client side: on sessions negotiated at 2026-07-28, Ping now returns a *jsonrpc.Error with CodeMethodNotFound without a round trip, instead of sending the removed method and surfacing whatever the server does with it.

• Corrected (per review): on lenient servers a params-less ping currently succeeds (it takes the legacy path and skips the removed-method branch), so this is a behavior change for that case — as any fix in this area must be, since injecting _meta would equally convert the ping into a new-protocol request that hits the removed-method branch. On strict transports both forms fail today: meta-less with -32020 header-mismatch, meta-injected with MethodNotFound (live evidence: mcp.svelte.dev).
• The error message mirrors the server's own phrasing for removed methods and names the capability list requests that do verify liveness (tools/list, resources/list, prompts/list).
• The cmd test's readiness check now relies on the connect itself (handshake or discovery round trip), since ping is unavailable on those sessions.
• Verified by TestClientPingRemovedOnNewProtocol, which uses a plain Connect (in-memory transports negotiate 2026-07-28 via server/discover) and asserts the typed error, its code, and that no ping request is sent.

[guglielmo-san]

@azilber thank you for reporting this. Contrary to what I said in previous issues that were opened relatively to this case, I might see now the advantage of injecting the _meta also for Ping method. This would allow to have the same failure for both stdio and streamable.
What do you think?

[chrikrah]

@azilber, two lines in the body do not match what I see in memory: "every 2026-07-28 ping fails today" and "cannot be reproduced against the SDK's own server". A default Client.Connect over NewInMemoryTransports negotiates 2026-07-28, and Ping succeeds on main. Ping sends params=null, so handle sees a legacy request and skips its removed-method branch. tools/list on the same session carries the envelope. From a scratch test outside the diff, with a receiving middleware on the server:

$ go test ./mcp/ -run TestZZProbePing -count=1 -v      # go1.27.1
== main @ 8c761a2
    usesNew=true
    server got ping params=null
    ping err=<nil>
    server got tools/list params={"_meta":{...,"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}
== PR @ 0b57f53
    usesNew=true
    ping err=mcp: ping is not supported on 2026-07-28 sessions (the method was removed); verify liveness with tools/list, resources/list, or prompts/list
    server got tools/list params={"_meta":{...,"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}
$ go test ./... -count=1      # probe file removed
main @ 8c761a2: ok  	github.com/modelcontextprotocol/go-sdk/mcp	32.965s
PR @ 0b57f53:   ok  	github.com/modelcontextprotocol/go-sdk/mcp	33.261s

blocking, if you keep this direction: return a *jsonrpc.Error with CodeMethodNotFound, not a fmt.Errorf. docs/protocol.md promises that code. The server also sends it for a ping that carries the new-protocol meta, so callers match one error with errors.As.

non-blocking: plain Connect already lands on 2026-07-28, and the cmd_test.go change relies on that too. TestClientPingRemovedOnNewProtocol can drop the cs.state write and its comment about the 2025-11-25 cap.

non-blocking: the Ping note in internal/docs/protocol.src.md still says the server answers MethodNotFound. With this change the client answers first, and docs/protocol.md regenerates from that source.

@guglielmo-san, the ping that works in memory today is the missing-envelope behavior from #1249, which you closed as by design. This PR turns it into a local error. Is that the direction you want for #1377?

[azilber]

Thanks both — and thanks for the correction, @chrikrah: you're right that today's in-memory ping succeeds (params=null takes the legacy path and skips the removed-method branch), so "no working behavior is lost" in my description was wrong for lenient servers. Both directions under discussion end that success: injecting _meta converts the ping into a new-protocol request, which then hits the removed-method branch too (I prototyped that first — it's what flipped cmd_test from pong to MethodNotFound).

On @guglielmo-san's question — I'd still lean fail-fast, for one main reason: injecting the SEP-2575 _meta stamps the request as following 2026-07-28, for a method 2026-07-28 deleted. Both approaches reach the same terminal state on spec-correct servers (live check against mcp.svelte.dev: with _meta injected, the -32020 goes away and the MethodNotFound remains — the server has no ping), but fail-fast gets there without the round trip and lets the error name the liveness alternatives. Per the blocking note I'll return *jsonrpc.Error with CodeMethodNotFound rather than fmt.Errorf, matching docs/protocol.md.

That said, the consistency argument for _meta (no client-side special casing; servers decide) is a real one, and the direction is squarely a #1377 call — happy to revise to whichever the WG prefers; the diff is ~10 lines either way. If fail-fast stands I'll also apply the non-blocking nits (drop the state write, fix the comment wording).

[guglielmo-san]

i would remove the "verify liveness" part, both in the error and in the comment above

[guglielmo-san]

@azilber ok lets proceed with the fail fast

[azilber]

Done — proceeding with the fail-fast per your ruling, and the "verify liveness" hint is removed from both the error message and the doc comment (67f44db); the message now matches the server's phrasing exactly. Naming replacement liveness checks is left to callers — in our CLI that mapping (ping → first declared capability list) lives client-side anyway.

Happy to make any further adjustments; otherwise this is ready for another look whenever convenient.

[guglielmo-san]

Suggested change

	//
	// On sessions negotiated at protocol version 2026-07-28 or later, Ping
	// returns a [jsonrpc.Error] with code [jsonrpc.CodeMethodNotFound] without a
	// round trip: the 2026-07-28 protocol schema removes the ping method. (A
	// ping sent without per-request _meta is additionally rejected by transports
	// that validate header/meta consistency, with -32020.)
	//
	// On sessions negotiated at protocol version 2026-07-28 or later, Ping
	// returns a [jsonrpc.Error] with code [jsonrpc.CodeMethodNotFound] without a
	// round trip: the 2026-07-28 protocol schema removes the ping method.

[guglielmo-san]

Let's also update the internal/docs/protocol.src.md as still says "the server returns MethodNotFound (-32601) for ping"

[azilber]

Both applied in 852eafd:

• The Ping doc comment is now exactly the suggested two sentences (the _meta/-32020 parenthetical is gone).
• internal/docs/protocol.src.md no longer attributes the error to the server: the note now reads "when a session negotiates 2026-07-28 or later, Ping returns MethodNotFound (-32601) locally, without a round trip, and KeepAlive should not be enabled." docs/protocol.md regenerated with go generate ./internal/docs.

No behavior change; tests unchanged.