feat: harden SEP-2322 MRTR support

Add a request-state integrity codec, expand MRTR edge-case coverage, and
document the end-to-end flow on top of the behavior support in #929.

- Add opt-in `request-state` feature with `RequestStateCodec`, an HMAC-SHA256
  seal/open helper for the untrusted `requestState` echoed by clients. Servers
  can still build the string by hand via `InputRequiredResult::from_request_state`.
- Expand `test_mrtr_behavior` to cover multi-round, multiple concurrent input
  requests, state-only backoff, max-rounds, handler errors, byte-exact
  requestState echo, prompts/get and resources/read, and pre-2026 version gating.
- Add the `servers_mrtr` example and MRTR usage docs.

Author: DaleSeo

crates/rmcp/Cargo.toml

@@ -22,6 +22,7 @@ features = [
   "client-side-sse",
   "elicitation",
   "macros",
+  "request-state",
   "reqwest",
   "reqwest-native-tls",
   "reqwest-tls-no-provider",
@@ -64,6 +65,10 @@ schemars = { version = "1.0", optional = true, features = ["chrono04"] }
 # for image encoding
 base64 = { version = "0.22", optional = true }
 
+# for SEP-2322 requestState integrity sealing (opt-in via the `request-state` feature)
+hmac = { version = "0.12", optional = true }
+sha2 = { version = "0.10", optional = true }
+
 # for HTTP client
 reqwest = { version = "0.13.2", default-features = false, features = [
   "json",
@@ -120,6 +125,9 @@ server = ["transport-async-rw", "dep:schemars", "dep:pastey"]
 macros = ["dep:rmcp-macros", "dep:pastey"]
 elicitation = ["dep:url"]
 
+# SEP-2322 requestState integrity helper (HMAC-SHA256 seal/open codec)
+request-state = ["dep:hmac", "dep:sha2", "base64"]
+
 # reqwest http client
 __reqwest = ["dep:reqwest"]
 
@@ -304,6 +312,11 @@ name = "test_custom_request"
 required-features = ["server", "client"]
 path = "tests/test_custom_request.rs"
 
+[[test]]
+name = "test_mrtr_behavior"
+required-features = ["server", "client"]
+path = "tests/test_mrtr_behavior.rs"
+
 [[test]]
 name = "test_prompt_macros"
 required-features = ["server", "client"]

crates/rmcp/src/model.rs

@@ -14,6 +14,8 @@ mod extension;
 mod meta;
 mod mrtr;
 mod prompt;
+#[cfg(feature = "request-state")]
+mod request_state;
 mod resource;
 mod serde_impl;
 mod task;
@@ -26,6 +28,8 @@ pub use extension::*;
 pub use meta::*;
 pub use mrtr::*;
 pub use prompt::*;
+#[cfg(feature = "request-state")]
+pub use request_state::*;
 pub use resource::*;
 use serde::{Deserialize, Serialize, de::DeserializeOwned};
 use serde_json::Value;

crates/rmcp/src/model/mrtr.rs

@@ -10,6 +10,31 @@
 //! [`InputRequiredResult`] instead of the normal result. The client fulfills the
 //! [`InputRequests`], then retries the original request with [`InputResponses`] and
 //! the echoed `requestState`.
+//!
+//! # Using MRTR
+//!
+//! **Server:** return an [`InputRequiredResult`] from a tool/prompt/resource
+//! handler via the matching outcome enum ([`CallToolResponse`],
+//! [`GetPromptResponse`], [`ReadResourceResponse`]). The SDK only lets an
+//! `InputRequiredResult` reach a peer that negotiated protocol version
+//! `2026-07-28` or newer; older peers get a protocol error instead.
+//!
+//! **Client:** the high-level `RunningService` helpers — `call_tool`,
+//! `get_prompt`, and `read_resource` — automatically fulfil each
+//! [`InputRequest`] through the local `ClientHandler` and retry, up to
+//! [`DEFAULT_MRTR_MAX_ROUNDS`]. Use the `*_once` variants (e.g.
+//! `call_tool_once`) to receive an [`InputRequiredResult`] directly and drive
+//! the rounds yourself.
+//!
+//! # `requestState` is untrusted
+//!
+//! The client echoes `requestState` back verbatim, so a stateless server that
+//! stores meaningful data in it MUST verify integrity before trusting the echoed
+//! value. Enable the `request-state` feature and use `RequestStateCodec` to seal
+//! and open it, or keep the state server-side and use `requestState` only as an
+//! opaque handle.
+//!
+//! A complete runnable walkthrough lives in the `servers_mrtr` example.
 
 use std::collections::BTreeMap;