Detect whether an MCP server speaks the modern stateless revision or the legacy initialize handshake and negotiate a version

Documented steps

1. Read https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning. Terminology: 'modern' = per-request _meta metadata (2026-07-28 and later), 'legacy' = the initialize handshake (2025-11-25 and earlier), 'dual-era' = supports both.
2. On stdio, probe with 'server/discover' before any other request, setting your preferred modern version in _meta. There is no HTTP status code to drive fallback on stdio.
3. Probe outcome 1: a DiscoverResult comes back. The server is modern — pick a mutually supported version from supportedVersions.
4. Probe outcome 2: a recognized modern JSON-RPC error comes back, e.g. UnsupportedProtocolVersionError (-32022). The server is modern but does not support your version — pick one from error.data.supported and do NOT fall back to initialize.
5. Probe outcome 3: any other error, or no response within a reasonable timeout. Treat the server as legacy and fall back to the initialize handshake.
6. Do NOT key the fallback to one specific error code. Legacy servers respond with implementation-defined errors, commonly -32601 or -32602, or do not respond at all.
7. Probe even if you only support modern versions (spec: RECOMMENDED), because some legacy servers will process an era-ambiguous method such as tools/call under legacy semantics without verifying that initialize occurred.
8. On Streamable HTTP, attempt a modern request first and inspect a 400 response BODY: a recognized modern JSON-RPC error (UnsupportedProtocolVersionError, MissingRequiredClientCapabilityError, or a header-validation failure) means the server is modern, so retry with an advertised version rather than falling back.
9. On Streamable HTTP, an empty or unrecognized 400 body means legacy: fall back to the initialize handshake, and if needed further to the deprecated HTTP+SSE transport (POST first; on 400/404/405 with an unrecognized body, GET and expect an 'endpoint' SSE event).
10. Handle -32022 anywhere it appears: read error.data.supported and error.data.requested, choose a mutually supported version, and retry. If there is no compatible version, surface an error to the user.
11. Remember a 404 with JSON-RPC -32601 from a modern server means the method is not implemented — that is deliberately distinguishable from a legacy HTTP+SSE 404.
12. Server side, to be dual-era: select behavior per request. A request carrying modern _meta is served statelessly per 2026-07-28; an initialize request selects legacy semantics scoped to the process (stdio) or session (HTTP). You MAY serve both eras concurrently.
13. Server side, if you support only modern versions: name your supported versions in any error you return to an initialize request, since a legacy client cannot fall forward on its own.
14. Verify against three fixtures — a modern-only server, a legacy-only server, and a dual-era server — and assert your client reaches a working state against all three without a hardcoded error-code check.