Add opt-in requestState sealing via RequestStateSecurity

[koic]

Motivation and Context

The SEP-2322 requestState continuation string leaves the server, sits in the client's hands, and comes back as client-controlled input. Without protection a client can read the server's continuation state, tamper with it (for example forging an already-answered elicitation), or replay a state issued for one call against another tool, other arguments, or another server. The multi-round-trip documentation of the Python SDK is explicit that the echo must be treated as untrusted input; its high-level server seals the state by default via RequestStateBoundary.

New MCP::Server::RequestStateSecurity (OpenSSL standard library only) brings that protection to this SDK as an opt-in:

• seal encrypts the plaintext state with AES-256-GCM (clients cannot read it, not merely verify it) inside a claims envelope binding an expiry window (ttl:, default 300 seconds, re-sealed each round), the originating method and target (tool/prompt name or resource URI), a digest of the originating arguments (stringified and sorted recursively, so symbol/string parses of identical JSON digest identically), and an optional audience:. The token format is v1.<base64url(iv || ciphertext || tag)> with the version prefix bound as GCM associated data, following the Python SDK's AESGCMRequestStateCodec.
• unseal verifies every claim fail-closed and raises InvalidStateError on tampering, expiry, or any mismatch.

Passing an instance via Server.new(request_state_security:) makes the seal/unseal transparent: issuance seals the requestState of an outgoing input_required result, and dispatch unseals the echoed token for tools/call, prompts/get, and resources/read before any handler runs, so server_context.request_state always reads the plaintext the handler wrote. A tampered, expired, or cross-call echo is rejected as -32602 with "Invalid or expired requestState", matching the Python SDK's frozen error.

Without the option the state crosses the wire exactly as the handler wrote it (the Python low-level Server behavior); the README documents that this is then the handler author's responsibility, and that multi-process deployments must share the key across workers.

The conformance fixture opts in with a random per-boot key, both to dogfood the feature and because the tampered-state scenario of the 2026-07-28 conformance requirements retries an MRTR request with a corrupted requestState and requires a JSON-RPC error; without integrity-checked state the fixture cannot detect the corruption. Every MRTR round trip completes within one server process, so no key persistence is needed. Sealing is transparent to the fixture tools, whose requestState plaintext round-trips unchanged, and the new test_input_required_result_tampered_state tool is therefore a plain MRTR elicitation flow; the tampered echo is rejected with -32602 by the server-level unsealing before dispatch ever reaches it.

Refs #382.

How Has This Been Tested?

New test/mcp/server/request_state_security_test.rb covers constructor validation, the seal/unseal round trip (opaque v1. token, plaintext not visible), expiry via time travel, fail-closed rejection of method/target/digest/audience mismatches, tampered and malformed tokens, and tokens sealed under a different key.

New tests in test/mcp/server_test.rb drive Server#handle with the modern envelope: transparent sealing on issuance and plaintext restoration on the retry leg, -32602 for tampered echoes and for echoes replayed against different arguments, and the pass-through default when request_state_security: is not set.

Against the fixture server at --spec-version 2026-07-28 (run with @modelcontextprotocol/conformance@alpha; the 2026-07-28 scenarios are not yet in a stable conformance release), sep-2322-reject-tampered-state reports SUCCESS, and the other 13 input-required-result-* scenarios stay green with sealing active, confirming that sealed states round-trip through the suite's retries without false rejections (the seal binds method, target, and an arguments digest, and the suite echoes all three unchanged). The --requirements 2025-11-25 server leg still passes.

Breaking Changes

None. The feature is opt-in via a new keyword argument that defaults to nil, in which case behavior is byte-identical to before.

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