feat(gateway): route by explicit X-Mcpmux-Workspace header

Clients that don't report MCP `roots` reliably — notably Cursor, which
multiplexes one MCP host across windows with `roots.listChanged=false` —
could not be routed to the right workspace binding, so `@mux` saw another
window's FeatureSet. `roots` is also deprecated (SEP-2577) and sessions are
being removed (SEP-2575/2567), so connection-carried identity, not the
client's roots, is the durable signal.

Add an `X-Mcpmux-Workspace` request header whose value is the workspace root
path. The OAuth middleware pins it into SessionRootsRegistry, where it
shadows the client's probed roots in `get()`. Because the resolver, the
on-demand probe skip, and the prompt-root derivation all read roots through
`get()`, the header flows through Tier 1 unchanged — exact binding match,
else Space default — and is authoritative over a stale or absent reported
root. No new resolver tier, parameter, or DB migration; the header value is
just a workspace root normalized like any other.

Tests: registry pin/shadow/clear units; resolver integration cases proving a
pinned root routes to its binding with no reported roots, overrides a
conflicting reported root, and falls back to Space default when unmapped.

Claude-Session: https://claude.ai/code/session_01Baan9JmzR43uxxRUh7CAMF
Signed-off-by: Mohammod Al Amin Ashik <maa.ashik00@gmail.com>

Author: its-mash

Cargo.lock

@@ -113,6 +113,32 @@ pub async fn mcp_oauth_middleware(
         space_id.to_string().parse().expect("valid header value"),
     );
 
+    // Pin an explicit workspace root advertised by the client via the
+    // `X-Mcpmux-Workspace` header (injected by McpMux's per-workspace client
+    // configs). It shadows the client's MCP-reported roots in the resolver, so
+    // a connection routes to its workspace binding even when the client never
+    // reports `roots` or reports a stale one (e.g. Cursor sharing one MCP host
+    // across windows). Unlike client/space id above, this header is
+    // client-asserted — the same trust model as MCP roots: any approved local
+    // client can claim any binding (see FeatureSetResolver trust model). Keyed
+    // by the `mcp-session-id` the client echoes on every post-initialize
+    // request (the same key the handler stores reported roots under).
+    let pin = {
+        let headers = request.headers();
+        let sid = headers
+            .get("mcp-session-id")
+            .and_then(|v| v.to_str().ok())
+            .map(str::to_owned);
+        let ws = headers
+            .get("x-mcpmux-workspace")
+            .and_then(|v| v.to_str().ok())
+            .map(str::to_owned);
+        sid.zip(ws)
+    };
+    if let Some((sid, ws)) = pin {
+        services.session_roots.set_pinned(&sid, &ws);
+    }
+
     // Extract MCP method from body if POST
     let mcp_method = if request.method() == axum::http::Method::POST {
         use axum::body::to_bytes;

crates/mcpmux-gateway/src/mcp/oauth_middleware.rs

@@ -76,6 +76,19 @@
 //!
 //! Roots-capable detection is stamped at `on_initialized` time into
 //! [`SessionRootsRegistry::set_roots_capable`].
+//!
+//! # Explicit workspace root via the `X-Mcpmux-Workspace` header
+//!
+//! A connection can carry an explicit workspace root in the
+//! `X-Mcpmux-Workspace` HTTP header, injected by McpMux's per-workspace client
+//! configs. The OAuth middleware pins it into
+//! [`SessionRootsRegistry::set_pinned`], where it **shadows** the client's
+//! probed MCP roots in [`SessionRootsRegistry::get`]. Because this resolver
+//! reads roots exclusively through `get`, a pinned root flows through Tier 1
+//! unchanged — an exact binding match, else the Space default — with no extra
+//! tier or parameter. This is the deterministic path for clients that don't
+//! report `roots` reliably (e.g. Cursor multiplexing one MCP host across
+//! windows): the header always wins over a stale or absent reported root.
 
 use std::sync::Arc;
 use std::time::Duration;

crates/mcpmux-gateway/src/services/feature_set_resolver.rs

@@ -14,6 +14,7 @@ use std::time::{Duration, Instant};
 
 use dashmap::DashMap;
 use mcpmux_core::normalize_workspace_root;
+use tracing::debug;
 
 /// Thread-safe registry mapping `mcp-session-id` to the caller's reported
 /// workspace roots, plus the most recently resolved feature-set id so the
@@ -66,6 +67,18 @@ pub struct SessionRootsRegistry {
     /// roots-capable client from flashing the default FeatureSet and then
     /// flipping to its mapped one the instant its root lands.
     first_seen: DashMap<String, Instant>,
+    /// `session_id -> explicit workspace root pinned via the
+    /// `X-Mcpmux-Workspace` HTTP header`.
+    ///
+    /// McpMux's per-workspace client configs inject that header with the
+    /// folder's path, so a connection routes to its workspace binding even
+    /// when the client never reports MCP `roots` or reports a stale one (e.g.
+    /// Cursor sharing a single MCP host across windows, with
+    /// `roots.listChanged = false`). A pinned root is **authoritative**: it
+    /// shadows the probed [`Self::map`] roots in [`Self::get`], so the
+    /// resolver, the on-demand probe skip, and the prompt-root derivation all
+    /// honor the header with no special-casing. Already normalized on insert.
+    pinned: DashMap<String, String>,
 }
 
 impl SessionRootsRegistry {
@@ -77,6 +90,7 @@ impl SessionRootsRegistry {
             last_probe: DashMap::new(),
             probe_lock: DashMap::new(),
             first_seen: DashMap::new(),
+            pinned: DashMap::new(),
         })
     }
 
@@ -155,10 +169,53 @@ impl SessionRootsRegistry {
     }
 
     /// Retrieve the (already-normalized) roots for a session, if any.
+    ///
+    /// An explicit root pinned via the `X-Mcpmux-Workspace` header
+    /// ([`Self::set_pinned`]) takes precedence over — and entirely shadows —
+    /// the client's probed MCP roots. That single seam is what makes the
+    /// header authoritative everywhere `get` is consulted (resolver Tier 1,
+    /// the probe early-return, prompt-root derivation) without threading the
+    /// header through any of those call paths.
     pub fn get(&self, session_id: &str) -> Option<Vec<String>> {
+        if let Some(pinned) = self.pinned.get(session_id) {
+            return Some(vec![pinned.clone()]);
+        }
         self.map.get(session_id).map(|v| v.clone())
     }
 
+    /// Pin an explicit workspace root for a session, sourced from the
+    /// `X-Mcpmux-Workspace` HTTP header. `raw_root` is a filesystem path or
+    /// `file://` URI; it's normalized like every other root before storage.
+    /// A value that normalizes to empty is ignored (no pin), so a malformed
+    /// header falls back to the client's reported roots rather than denying.
+    /// Cheap to call on the request hot path: redundant writes (same
+    /// normalized value already pinned) are skipped to avoid shard churn.
+    pub fn set_pinned(&self, session_id: &str, raw_root: &str) {
+        let normalized = normalize_workspace_root(raw_root);
+        if normalized.is_empty() {
+            return;
+        }
+        if self
+            .pinned
+            .get(session_id)
+            .is_some_and(|v| *v == normalized)
+        {
+            return;
+        }
+        debug!(
+            %session_id,
+            workspace_root = %normalized,
+            "[SessionRoots] pinned explicit workspace root from X-Mcpmux-Workspace header",
+        );
+        self.pinned.insert(session_id.to_string(), normalized);
+    }
+
+    /// The explicit workspace root pinned for a session via the header, if any
+    /// (already normalized).
+    pub fn get_pinned(&self, session_id: &str) -> Option<String> {
+        self.pinned.get(session_id).map(|v| v.clone())
+    }
+
     /// Drop a session's roots — call on client disconnect.
     pub fn remove(&self, session_id: &str) {
         self.map.remove(session_id);
@@ -167,6 +224,7 @@ impl SessionRootsRegistry {
         self.last_probe.remove(session_id);
         self.probe_lock.remove(session_id);
         self.first_seen.remove(session_id);
+        self.pinned.remove(session_id);
     }
 
     /// Compare-and-set the session's resolved feature-set id. Returns `true`
@@ -311,6 +369,56 @@ mod tests {
         assert_eq!(reg.len(), 0);
     }
 
+    #[test]
+    fn test_pinned_root_shadows_reported_roots() {
+        let reg = SessionRootsRegistry::default();
+        #[cfg(windows)]
+        let (reported, pin_in, pin_norm) = (
+            "file:///D:/reported/",
+            "D:\\Pinned\\Path",
+            "d:\\pinned\\path",
+        );
+        #[cfg(not(windows))]
+        let (reported, pin_in, pin_norm) = (
+            "file:///home/u/reported/",
+            "/home/u/Pinned",
+            "/home/u/Pinned",
+        );
+
+        reg.set("sess-1", [reported]);
+        reg.set_pinned("sess-1", pin_in);
+
+        // The pinned (header) root entirely shadows the probed root.
+        assert_eq!(reg.get("sess-1"), Some(vec![pin_norm.to_string()]));
+        assert_eq!(reg.get_pinned("sess-1"), Some(pin_norm.to_string()));
+    }
+
+    #[test]
+    fn test_set_pinned_ignores_empty_and_normalizes() {
+        let reg = SessionRootsRegistry::default();
+        // Whitespace/garbage that normalizes to empty leaves no pin, so a
+        // malformed header falls back to reported roots rather than denying.
+        reg.set_pinned("sess-1", "   ");
+        assert!(reg.get_pinned("sess-1").is_none());
+
+        #[cfg(windows)]
+        let (pin_in, pin_norm) = ("file:///D:/Foo/", "d:\\foo");
+        #[cfg(not(windows))]
+        let (pin_in, pin_norm) = ("file:///home/u/Foo/", "/home/u/Foo");
+        reg.set_pinned("sess-1", pin_in);
+        assert_eq!(reg.get_pinned("sess-1"), Some(pin_norm.to_string()));
+    }
+
+    #[test]
+    fn test_remove_clears_pinned() {
+        let reg = SessionRootsRegistry::default();
+        reg.set_pinned("sess-1", "/p");
+        assert!(reg.get_pinned("sess-1").is_some());
+        reg.remove("sess-1");
+        assert!(reg.get_pinned("sess-1").is_none());
+        assert!(reg.get("sess-1").is_none());
+    }
+
     #[test]
     fn test_record_resolution_flips_on_change() {
         let reg = SessionRootsRegistry::default();

crates/mcpmux-gateway/src/services/session_roots.rs

@@ -655,3 +655,85 @@ async fn two_sessions_on_same_root_resolve_to_the_same_binding() {
     assert_eq!(r2.feature_set_ids, vec![f.fs_a_id.clone()]);
     assert_eq!(r1.space_id, r2.space_id);
 }
+
+// ---------------------------------------------------------------------------
+// Explicit workspace root via the X-Mcpmux-Workspace header (pinned root)
+// ---------------------------------------------------------------------------
+
+#[tokio::test]
+async fn pinned_header_root_routes_to_binding_without_any_reported_roots() {
+    // The deterministic fix for clients that don't report MCP roots reliably
+    // (e.g. Cursor multiplexing one MCP host across windows): a session flagged
+    // explicitly rootless, with no reported roots, still routes to its
+    // workspace binding purely from the X-Mcpmux-Workspace header the gateway
+    // pinned.
+    let f = Fixture::new().await;
+    f.binding_repo
+        .create(&WorkspaceBinding::new(
+            normalize_workspace_root(test_root()),
+            f.space_id,
+            f.fs_a_id.clone(),
+        ))
+        .await
+        .unwrap();
+
+    f.session_roots.set_roots_capable("s", false); // client says it has no roots
+    f.session_roots.set_pinned("s", test_root()); // ...but the header pins one
+
+    let r = f.resolver.resolve(Some("s"), None).await.unwrap();
+    assert_eq!(r.source, ResolutionSource::WorkspaceBinding);
+    assert_eq!(r.space_id, Some(f.space_id));
+    assert_eq!(r.feature_set_ids, vec![f.fs_a_id]);
+}
+
+#[tokio::test]
+async fn pinned_header_root_overrides_a_conflicting_reported_root() {
+    // The header is authoritative. When the client reports a stale/wrong root
+    // AND a header root is pinned, the pinned one wins — exactly the Cursor
+    // "reported the wrong window's root" failure, now corrected.
+    let f = Fixture::new().await;
+    let (reported, pinned) = if cfg!(windows) {
+        ("d:\\work\\reported", "d:\\work\\pinned")
+    } else {
+        ("/work/reported", "/work/pinned")
+    };
+    f.binding_repo
+        .create(&WorkspaceBinding::new(
+            normalize_workspace_root(reported),
+            f.space_id,
+            f.fs_a_id.clone(),
+        ))
+        .await
+        .unwrap();
+    f.binding_repo
+        .create(&WorkspaceBinding::new(
+            normalize_workspace_root(pinned),
+            f.space_id,
+            f.fs_b_id.clone(),
+        ))
+        .await
+        .unwrap();
+
+    f.session_roots.set("s", [reported]);
+    f.session_roots.set_roots_capable("s", true);
+    f.session_roots.set_pinned("s", pinned);
+
+    let r = f.resolver.resolve(Some("s"), None).await.unwrap();
+    assert_eq!(r.source, ResolutionSource::WorkspaceBinding);
+    // Resolved to the PINNED root's FS (B), not the reported root's FS (A).
+    assert_eq!(r.feature_set_ids, vec![f.fs_b_id]);
+    assert_ne!(r.feature_set_ids, vec![f.fs_a_id]);
+}
+
+#[tokio::test]
+async fn pinned_header_root_without_binding_falls_back_to_space_default() {
+    // A header root for an as-yet-unmapped folder still works out of the box on
+    // the Space default (upstream emits WorkspaceNeedsBinding so the user can
+    // attach an explicit mapping).
+    let f = Fixture::new().await;
+    f.session_roots.set_pinned("s", test_root());
+    let r = f.resolver.resolve(Some("s"), None).await.unwrap();
+    assert_eq!(r.source, ResolutionSource::SpaceDefault);
+    assert_eq!(r.feature_set_ids, vec![f.starter_fs_id.clone()]);
+    assert_eq!(r.space_id, Some(f.space_id));
+}