refactor: rename stateful_mode to legacy_session_mode

Author: alexhancock

conformance/src/bin/server.rs

@@ -1229,7 +1229,7 @@ async fn main() -> anyhow::Result<()> {
     let server = ConformanceServer::new();
     let stateless = std::env::var_os("STATELESS").is_some();
     let config = StreamableHttpServerConfig::default()
-        .with_stateful_mode(!stateless)
+        .with_legacy_session_mode(!stateless)
         .with_json_response(stateless);
     let service = StreamableHttpService::new(
         move || Ok(server.clone()),

crates/rmcp/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **BREAKING**: rename `StreamableHttpServerConfig::stateful_mode` to `legacy_session_mode` (and the builder `with_stateful_mode` to `with_legacy_session_mode`) to clarify that the option only affects legacy protocol versions (`< 2026-07-28`); per SEP-2567 the `2026-07-28` draft version is always served statelessly ([#999](https://github.com/modelcontextprotocol/rust-sdk/pull/999))
+
 ## [2.2.0](https://github.com/modelcontextprotocol/rust-sdk/compare/rmcp-v2.1.0...rmcp-v2.2.0) - 2026-07-08
 
 ### Added

crates/rmcp/src/transport/streamable_http_server/session.rs

@@ -13,7 +13,7 @@
 //!
 //! * [`local::LocalSessionManager`] — in-memory session store (default).
 //! * [`never::NeverSessionManager`] — rejects all session operations, used
-//!   when stateful mode is disabled.
+//!   when legacy session mode is disabled.
 //!
 //! # Custom session managers
 //!

crates/rmcp/src/transport/streamable_http_server/tower.rs

@@ -59,8 +59,13 @@ pub struct StreamableHttpServerConfig {
     pub sse_retry: Option<Duration>,
     /// If true, the server will create a session for each request and keep it alive.
     /// When enabled, SSE priming events are sent to enable client reconnection.
-    pub stateful_mode: bool,
-    /// When true and `stateful_mode` is false, the server prefers
+    ///
+    /// Only applies to legacy protocol versions (`< 2026-07-28`). Per SEP-2567,
+    /// sessions are removed from the `2026-07-28` draft version, so requests
+    /// negotiating that version are always served statelessly regardless of
+    /// this setting.
+    pub legacy_session_mode: bool,
+    /// When true and `legacy_session_mode` is false, the server prefers
     /// `Content-Type: application/json` for simple request-response tools.
     /// If the handler emits a notification or request before the final response,
     /// the server falls back to `text/event-stream` so no message is lost.
@@ -130,7 +135,7 @@ impl Default for StreamableHttpServerConfig {
         Self {
             sse_keep_alive: Some(Duration::from_secs(15)),
             sse_retry: Some(Duration::from_secs(3)),
-            stateful_mode: true,
+            legacy_session_mode: true,
             json_response: false,
             cancellation_token: CancellationToken::new(),
             allowed_hosts: vec!["localhost".into(), "127.0.0.1".into(), "::1".into()],
@@ -176,8 +181,8 @@ impl StreamableHttpServerConfig {
         self
     }
 
-    pub fn with_stateful_mode(mut self, stateful: bool) -> Self {
-        self.stateful_mode = stateful;
+    pub fn with_legacy_session_mode(mut self, legacy_session_mode: bool) -> Self {
+        self.legacy_session_mode = legacy_session_mode;
         self
     }
 
@@ -690,7 +695,7 @@ fn validate_origin_header(
 ///
 /// ## Session management
 ///
-/// When [`StreamableHttpServerConfig::stateful_mode`] is `true` (the default),
+/// When [`StreamableHttpServerConfig::legacy_session_mode`] is `true` (the default),
 /// the server creates a session for each client that sends an `initialize`
 /// request. The session ID is returned in the `Mcp-Session-Id` response header
 /// and the client must include it on all subsequent requests.
@@ -1186,13 +1191,13 @@ where
             return response;
         }
         let method = request.method().clone();
-        let allowed_methods = match self.config.stateful_mode {
+        let allowed_methods = match self.config.legacy_session_mode {
             true => "GET, POST, DELETE",
             false => "POST",
         };
-        let result = match (method, self.config.stateful_mode) {
+        let result = match (method, self.config.legacy_session_mode) {
             (Method::POST, _) => self.handle_post(request).await,
-            // if we're not in stateful mode, we don't support GET or DELETE because there is no session
+            // if legacy session mode is disabled, we don't support GET or DELETE because there is no session
             (Method::GET, true) => self.handle_get(request).await,
             (Method::DELETE, true) => self.handle_delete(request).await,
             _ => {
@@ -1372,7 +1377,7 @@ where
         };
 
         let use_session =
-            self.config.stateful_mode && is_legacy_request(Some(&message), &part.headers);
+            self.config.legacy_session_mode && is_legacy_request(Some(&message), &part.headers);
 
         if use_session {
             // do we have a session id?

crates/rmcp/tests/test_discover_http_client_startup.rs

@@ -54,7 +54,7 @@ async fn discover_http_client_bootstraps_headers_without_initialize() {
             || Ok(DiscoverHttpServer),
             Default::default(),
             StreamableHttpServerConfig::default()
-                .with_stateful_mode(false)
+                .with_legacy_session_mode(false)
                 .with_json_response(true)
                 .with_cancellation_token(ct.child_token()),
         );

crates/rmcp/tests/test_server_discover_http.rs

@@ -32,16 +32,16 @@ impl ServerHandler for DiscoveryServer {
 }
 
 async fn spawn_server(json_response: bool) -> (reqwest::Client, String, CancellationToken) {
-    spawn_server_with_stateful_mode(json_response, false).await
+    spawn_server_with_legacy_session_mode(json_response, false).await
 }
 
-async fn spawn_server_with_stateful_mode(
+async fn spawn_server_with_legacy_session_mode(
     json_response: bool,
-    stateful_mode: bool,
+    legacy_session_mode: bool,
 ) -> (reqwest::Client, String, CancellationToken) {
     let cancellation_token = CancellationToken::new();
     let config = StreamableHttpServerConfig::default()
-        .with_stateful_mode(stateful_mode)
+        .with_legacy_session_mode(legacy_session_mode)
         .with_json_response(json_response)
         .with_sse_keep_alive(None)
         .with_cancellation_token(cancellation_token.clone());
@@ -136,8 +136,8 @@ async fn discover_returns_server_metadata_without_session() {
 }
 
 #[tokio::test]
-async fn discover_does_not_require_initialization_in_stateful_mode() {
-    let (client, url, cancellation_token) = spawn_server_with_stateful_mode(true, true).await;
+async fn discover_does_not_require_initialization_in_legacy_session_mode() {
+    let (client, url, cancellation_token) = spawn_server_with_legacy_session_mode(true, true).await;
 
     let response = post_discover(&client, &url, "2025-11-25", Some("2025-11-25")).await;
 

crates/rmcp/tests/test_stateless_protocol_version.rs

@@ -16,7 +16,7 @@ use common::calculator::Calculator;
 
 fn stateless_json_config() -> StreamableHttpServerConfig {
     StreamableHttpServerConfig::default()
-        .with_stateful_mode(false)
+        .with_legacy_session_mode(false)
         .with_json_response(true)
         .with_sse_keep_alive(None)
         .with_cancellation_token(CancellationToken::new())

crates/rmcp/tests/test_streamable_http_disconnect_cancel.rs

@@ -81,7 +81,7 @@ async fn spawn_stateless_server(json_response: bool) -> anyhow::Result<TestServe
 
     let server_ct = CancellationToken::new();
     let config = StreamableHttpServerConfig::default()
-        .with_stateful_mode(false)
+        .with_legacy_session_mode(false)
         .with_json_response(json_response)
         // A short keep-alive lets the SSE server notice a dropped connection
         // quickly (hyper only observes the disconnect on its next write).

crates/rmcp/tests/test_streamable_http_json_response.rs

@@ -103,7 +103,7 @@ async fn stateless_json_response_returns_application_json() -> anyhow::Result<()
     let ct = CancellationToken::new();
     let (client, url, ct) = spawn_server(
         StreamableHttpServerConfig::default()
-            .with_stateful_mode(false)
+            .with_legacy_session_mode(false)
             .with_json_response(true)
             .with_sse_keep_alive(None)
             .with_cancellation_token(ct.child_token()),
@@ -145,7 +145,7 @@ async fn stateless_json_response_falls_back_to_sse_for_progress() -> anyhow::Res
     let ct = CancellationToken::new();
     let (client, url, ct) = spawn_progress_server(
         StreamableHttpServerConfig::default()
-            .with_stateful_mode(false)
+            .with_legacy_session_mode(false)
             .with_json_response(true)
             .with_sse_keep_alive(None)
             .with_cancellation_token(ct.child_token()),
@@ -197,7 +197,7 @@ async fn stateless_sse_mode_default_unchanged() -> anyhow::Result<()> {
     let ct = CancellationToken::new();
     let (client, url, ct) = spawn_server(
         StreamableHttpServerConfig::default()
-            .with_stateful_mode(false)
+            .with_legacy_session_mode(false)
             .with_sse_keep_alive(None)
             .with_cancellation_token(ct.child_token()),
     )
@@ -234,9 +234,9 @@ async fn stateless_sse_mode_default_unchanged() -> anyhow::Result<()> {
 }
 
 #[tokio::test]
-async fn json_response_ignored_in_stateful_mode() -> anyhow::Result<()> {
+async fn json_response_ignored_in_legacy_session_mode() -> anyhow::Result<()> {
     let ct = CancellationToken::new();
-    // json_response: true has no effect when stateful_mode: true — server still uses SSE
+    // json_response: true has no effect when legacy_session_mode: true — server still uses SSE
     let (client, url, ct) = spawn_server(
         StreamableHttpServerConfig::default()
             .with_json_response(true)

crates/rmcp/tests/test_streamable_http_priming.rs

@@ -14,7 +14,7 @@ use common::calculator::Calculator;
 async fn test_priming_on_stream_start() -> anyhow::Result<()> {
     let ct = CancellationToken::new();
 
-    // stateful_mode: true automatically enables priming with DEFAULT_RETRY_INTERVAL (3 seconds)
+    // legacy_session_mode: true automatically enables priming with DEFAULT_RETRY_INTERVAL (3 seconds)
     let service: StreamableHttpService<Calculator, LocalSessionManager> =
         StreamableHttpService::new(
             || Ok(Calculator::new()),
@@ -416,7 +416,7 @@ async fn test_priming_on_stream_close() -> anyhow::Result<()> {
     let ct = CancellationToken::new();
     let session_manager = Arc::new(LocalSessionManager::default());
 
-    // stateful_mode: true automatically enables priming with DEFAULT_RETRY_INTERVAL (3 seconds)
+    // legacy_session_mode: true automatically enables priming with DEFAULT_RETRY_INTERVAL (3 seconds)
     let service = StreamableHttpService::new(
         || Ok(Calculator::new()),
         session_manager.clone(),