Add Stateless Lifecycle Foundations per SEP-2575

[koic]

Motivation and Context

SEP-2575 (modelcontextprotocol/modelcontextprotocol#2575, merged for the 2026-07-28 spec release) replaces the initialize handshake with a stateless "modern" lifecycle: every request carries its protocol version, client info, and client capabilities in reserved _meta keys, and the server validates each request independently. This change lays the shared vocabulary for that lifecycle without changing any behavior:

• MCP::Configuration gains LATEST_MODERN_PROTOCOL_VERSION ("2026-07-28"), SUPPORTED_MODERN_PROTOCOL_VERSIONS, and Configuration.modern_protocol_version?. Modern versions are deliberately kept out of SUPPORTED_STABLE_PROTOCOL_VERSIONS so initialize can never negotiate them and protocol_version= keeps rejecting them.
• MCP::ErrorCodes gains HEADER_MISMATCH (-32020), completing the spec's stateless lifecycle error code block alongside the existing -32021/-32022 constants.
• New MCP::RequestEnvelope parses and validates the per-request _meta triple (io.modelcontextprotocol/protocolVersion, clientInfo, clientCapabilities, plus the optional deprecated logLevel). A request is classified as modern only when the full triple is present, matching the TypeScript SDK's RequestMetaEnvelopeSchema and the Python SDK's _has_modern_envelope, so partial or legacy _meta entries keep flowing through the legacy path untouched.
• New typed errors Server::UnsupportedProtocolVersionError (-32022 with data: { supported:, requested: }) and Server::MissingRequiredClientCapabilityError (-32021 with data: { requiredCapabilities: }) reuse the established RequestHandlerError error_code/error_data plumbing (the -32042 URL elicitation precedent).

Nothing dispatches through RequestEnvelope yet; the server-side modern handling, transport routing, and client support build on this in follow-up changes.

Refs #389.

How Has This Been Tested?

New test/mcp/request_envelope_test.rb covers the modern-triple classification (full triple, partial triple, string keys, legacy progressToken), parsed field access, the -32022 error data shape, and invalid-request errors for incomplete or mistyped triples. test/mcp/configuration_test.rb asserts the new constants, the predicate, and that modern versions stay rejected by protocol_version=. test/mcp/server_test.rb asserts both typed errors surface on the wire with their SEP-2575 codes and data through Server#handle. test/mcp/error_codes_test.rb pins -32020.

Breaking Changes

None. Constants and classes are additive; no request path changes behavior.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

[atesgoral]

The spec doesn't seem to adopt the term "modern" to refer to this statetless mode. Can we use "stateless" instead of "modern"?

[koic]

Thanks, good point. The spec says "stateless" rather than "modern", so the term isn't spec-derived.

I chose "modern" (paired with "legacy") to follow the reference SDKs, which treat this as a two-era ("dual-era") split:

• TypeScript: packages/core-internal/src/shared/protocolEras.ts, SUPPORTED_MODERN_PROTOCOL_VERSIONS in versionNegotiation.ts / createMcpHandler.ts / serveStdio.ts, plus an examples/dual-era/ example.
• Python: MODERN_PROTOCOL_VERSIONS (mcp-types/.../version.py, client/_probe.py) and _has_modern_envelope (server/runner.py), plus an examples/stories/dual_era/ example.

There's also a naming collision to avoid. StreamableHTTPTransport already has a stateless: option (SEP-2567, ephemeral per-request sessions on the legacy lifecycle). That's a different axis from SEP-2575 (no initialize handshake), so reusing "stateless" for the lifecycle would make identifiers like SUPPORTED_STATELESS_PROTOCOL_VERSIONS or RequestEnvelope.stateless? ambiguous alongside the existing option. The "modern"/"legacy" pairing keeps the lifecycle axis distinct, which is likely why the TypeScript and Python SDKs adopted those terms as well.

That said, this is the foundational PR for the stack, so I'd like to settle on the terminology here. Would you still prefer "stateless", given the overlap with the existing stateless: option? If so, I can rename things and reconcile the existing option's naming and documentation. Otherwise, I'd prefer to keep "modern"/"legacy" for the lifecycle identifiers, since the concept-level terminology (the PR title and docs) already uses "stateless lifecycle".