feat(transport): add Unix domain socket client for streamable HTTP (#749)

* feat(transport): add Unix domain socket client for streamable HTTP

MCP hosts in Kubernetes environments with Envoy sidecars need to route
HTTP through Unix domain sockets because DNS-based URIs only resolve
via the proxy. Adds UnixSocketHttpClient implementing StreamableHttpClient
using hyper over tokio::net::UnixStream, gated behind the
transport-streamable-http-client-unix-socket feature.

Also extracts RESERVED_HEADERS, extract_scope_from_header, and
validate_custom_header into common/http_header.rs to share header
validation logic between the reqwest and unix socket implementations.

* fix(transport): address review feedback for unix socket transport

- Document one-connection-per-request behavior on UnixSocketHttpClient
- Reject empty socket paths and bare '@' in constructor with assert
- Add explicit dep:http to unix-socket feature for self-documenting deps
- Document MCP-Protocol-Version exception on RESERVED_HEADERS constant
- Fix test catch-all to echo request id instead of hardcoding 1
- Remove leftover sleep(100ms) in test_unix_socket_custom_headers
- Add blank line before macro comment in Cargo.toml

* fix(transport): fix CI failures for unix socket transport

- Use std::io::Error::other() instead of Error::new(ErrorKind::Other)
  to satisfy clippy::io_other_error on newer nightly
- Use #[tokio::test(flavor = "current_thread")] for unix socket tests
  since axum's serve(UnixListener) requires spawn_local
- Gate validate_custom_header behind client-side-sse feature since it
  references http::HeaderName which isn't available with default features

* fix(transport): fix CI failures for unix socket transport

axum::serve(UnixListener) uses spawn_local on Linux, which panics
outside a LocalSet. Replace with manual hyper HTTP/1.1 server that
accepts connections directly from the UnixListener, avoiding the
spawn_local requirement entirely.

* fix(transport): skip unix socket tests when local feature is enabled

The local feature causes ().serve(transport) to use spawn_local, which
requires a LocalSet. Gate the integration tests with not(feature = "local")
to match every other integration test in the repo.

Author: wpfleger96

crates/rmcp/Cargo.toml

@@ -62,6 +62,11 @@ uuid = { version = "1", features = ["v4"], optional = true }
 http-body = { version = "1", optional = true }
 http-body-util = { version = "0.1", optional = true }
 bytes = { version = "1", optional = true }
+
+# for unix socket transport
+hyper = { version = "1", features = ["client", "http1"], optional = true }
+hyper-util = { version = "0.1", features = ["tokio"], optional = true }
+
 # macro
 rmcp-macros = { workspace = true, optional = true }
 [target.'cfg(not(all(target_family = "wasm", target_os = "unknown")))'.dependencies]
@@ -112,6 +117,15 @@ client-side-sse = ["dep:sse-stream", "dep:http"]
 # Streamable HTTP client
 transport-streamable-http-client = ["client-side-sse", "transport-worker"]
 transport-streamable-http-client-reqwest = ["transport-streamable-http-client", "__reqwest"]
+transport-streamable-http-client-unix-socket = [
+  "transport-streamable-http-client",
+  "dep:hyper",
+  "dep:hyper-util",
+  "dep:http-body-util",
+  "dep:http",
+  "dep:bytes",
+  "tokio/net",
+]
 
 transport-async-rw = ["tokio/io-util", "tokio-util/codec"]
 transport-io = ["transport-async-rw", "tokio/io-std"]
@@ -139,6 +153,9 @@ schemars = ["dep:schemars"]
 tokio = { version = "1", features = ["full"] }
 schemars = { version = "1.1.0", features = ["chrono04"] }
 axum = { version = "0.8", default-features = false, features = ["http1", "tokio"] }
+hyper = { version = "1", features = ["server", "http1"] }
+hyper-util = { version = "0.1", features = ["tokio"] }
+tower-service = "0.3"
 url = "2.4"
 anyhow = "1.0"
 tracing-subscriber = { version = "0.3", features = [
@@ -266,6 +283,15 @@ name = "test_client_credentials"
 required-features = ["auth"]
 path = "tests/test_client_credentials.rs"
 
+[[test]]
+name = "test_unix_socket_transport"
+required-features = [
+  "client",
+  "server",
+  "transport-streamable-http-client-unix-socket",
+]
+path = "tests/test_unix_socket_transport.rs"
+
 [[test]]
 name = "test_streamable_http_stale_session"
 required-features = [

crates/rmcp/src/transport.rs

@@ -112,6 +112,8 @@ pub use streamable_http_server::tower::{StreamableHttpServerConfig, StreamableHt
 
 #[cfg(feature = "transport-streamable-http-client")]
 pub mod streamable_http_client;
+#[cfg(all(unix, feature = "transport-streamable-http-client-unix-socket"))]
+pub use common::unix_socket::UnixSocketHttpClient;
 #[cfg(feature = "transport-streamable-http-client")]
 pub use streamable_http_client::StreamableHttpClientTransport;
 

crates/rmcp/src/transport/common.rs

@@ -14,3 +14,6 @@ pub mod client_side_sse;
 
 #[cfg(feature = "auth")]
 pub mod auth;
+
+#[cfg(all(unix, feature = "transport-streamable-http-client-unix-socket"))]
+pub mod unix_socket;

crates/rmcp/src/transport/common/http_header.rs

@@ -3,3 +3,122 @@ pub const HEADER_LAST_EVENT_ID: &str = "Last-Event-Id";
 pub const HEADER_MCP_PROTOCOL_VERSION: &str = "MCP-Protocol-Version";
 pub const EVENT_STREAM_MIME_TYPE: &str = "text/event-stream";
 pub const JSON_MIME_TYPE: &str = "application/json";
+
+/// Reserved headers that must not be overridden by user-supplied custom headers.
+/// `MCP-Protocol-Version` is in this list but is allowed through because the worker
+/// injects it after initialization.
+pub(crate) const RESERVED_HEADERS: &[&str] = &[
+    "accept",
+    HEADER_SESSION_ID,
+    HEADER_MCP_PROTOCOL_VERSION, // allowed through by validate_custom_header; worker injects it post-init
+    HEADER_LAST_EVENT_ID,
+];
+
+/// Checks whether a custom header name is allowed.
+/// Returns `Ok(())` if allowed, `Err(name)` if rejected as reserved.
+/// `MCP-Protocol-Version` is reserved but allowed through (the worker injects it post-init).
+#[cfg(feature = "client-side-sse")]
+pub(crate) fn validate_custom_header(name: &http::HeaderName) -> Result<(), String> {
+    if RESERVED_HEADERS
+        .iter()
+        .any(|&r| name.as_str().eq_ignore_ascii_case(r))
+    {
+        if name
+            .as_str()
+            .eq_ignore_ascii_case(HEADER_MCP_PROTOCOL_VERSION)
+        {
+            return Ok(());
+        }
+        return Err(name.to_string());
+    }
+    Ok(())
+}
+
+/// Extracts the `scope=` parameter from a `WWW-Authenticate` header value.
+/// Handles both quoted (`scope="files:read files:write"`) and unquoted (`scope=read:data`) forms.
+pub(crate) fn extract_scope_from_header(header: &str) -> Option<String> {
+    let header_lowercase = header.to_ascii_lowercase();
+    let scope_key = "scope=";
+
+    if let Some(pos) = header_lowercase.find(scope_key) {
+        let start = pos + scope_key.len();
+        let value_slice = &header[start..];
+
+        if let Some(stripped) = value_slice.strip_prefix('"') {
+            if let Some(end_quote) = stripped.find('"') {
+                return Some(stripped[..end_quote].to_string());
+            }
+        } else {
+            let end = value_slice
+                .find(|c: char| c == ',' || c == ';' || c.is_whitespace())
+                .unwrap_or(value_slice.len());
+            if end > 0 {
+                return Some(value_slice[..end].to_string());
+            }
+        }
+    }
+
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn extract_scope_quoted() {
+        let header = r#"Bearer error="insufficient_scope", scope="files:read files:write""#;
+        assert_eq!(
+            extract_scope_from_header(header),
+            Some("files:read files:write".to_string())
+        );
+    }
+
+    #[test]
+    fn extract_scope_unquoted() {
+        let header = r#"Bearer scope=read:data, error="insufficient_scope""#;
+        assert_eq!(
+            extract_scope_from_header(header),
+            Some("read:data".to_string())
+        );
+    }
+
+    #[test]
+    fn extract_scope_missing() {
+        let header = r#"Bearer error="invalid_token""#;
+        assert_eq!(extract_scope_from_header(header), None);
+    }
+
+    #[test]
+    fn extract_scope_empty_header() {
+        assert_eq!(extract_scope_from_header("Bearer"), None);
+    }
+
+    #[cfg(feature = "client-side-sse")]
+    #[test]
+    fn validate_rejects_reserved_accept() {
+        let name = http::HeaderName::from_static("accept");
+        assert!(validate_custom_header(&name).is_err());
+    }
+
+    #[cfg(feature = "client-side-sse")]
+    #[test]
+    fn validate_rejects_reserved_session_id() {
+        let name = http::HeaderName::from_static("mcp-session-id");
+        assert!(validate_custom_header(&name).is_err());
+    }
+
+    #[cfg(feature = "client-side-sse")]
+    #[test]
+    fn validate_allows_mcp_protocol_version() {
+        let name = http::HeaderName::from_static("mcp-protocol-version");
+        assert!(validate_custom_header(&name).is_ok());
+    }
+
+    #[cfg(feature = "client-side-sse")]
+    #[test]
+    fn validate_allows_custom_header() {
+        let name = http::HeaderName::from_static("x-custom");
+        assert!(validate_custom_header(&name).is_ok());
+    }
+}

crates/rmcp/src/transport/common/reqwest/streamable_http_client.rs

@@ -9,8 +9,8 @@ use crate::{
     model::{ClientJsonRpcMessage, JsonRpcMessage, ServerJsonRpcMessage},
     transport::{
         common::http_header::{
-            EVENT_STREAM_MIME_TYPE, HEADER_LAST_EVENT_ID, HEADER_MCP_PROTOCOL_VERSION,
-            HEADER_SESSION_ID, JSON_MIME_TYPE,
+            EVENT_STREAM_MIME_TYPE, HEADER_LAST_EVENT_ID, HEADER_SESSION_ID, JSON_MIME_TYPE,
+            extract_scope_from_header, validate_custom_header,
         },
         streamable_http_client::*,
     },
@@ -22,38 +22,13 @@ impl From<reqwest::Error> for StreamableHttpError<reqwest::Error> {
     }
 }
 
-/// Reserved headers that must not be overridden by user-supplied custom headers.
-/// `MCP-Protocol-Version` is in this list but is allowed through because the worker
-/// injects it after initialization.
-const RESERVED_HEADERS: &[&str] = &[
-    "accept",
-    HEADER_SESSION_ID,
-    HEADER_MCP_PROTOCOL_VERSION,
-    HEADER_LAST_EVENT_ID,
-];
-
-/// Applies custom headers to a request builder, rejecting reserved headers
-/// except `MCP-Protocol-Version` (which the worker injects after init).
+/// Applies custom headers to a request builder, rejecting reserved headers.
 fn apply_custom_headers(
     mut builder: reqwest::RequestBuilder,
     custom_headers: HashMap<HeaderName, HeaderValue>,
 ) -> Result<reqwest::RequestBuilder, StreamableHttpError<reqwest::Error>> {
     for (name, value) in custom_headers {
-        if RESERVED_HEADERS
-            .iter()
-            .any(|&r| name.as_str().eq_ignore_ascii_case(r))
-        {
-            if name
-                .as_str()
-                .eq_ignore_ascii_case(HEADER_MCP_PROTOCOL_VERSION)
-            {
-                builder = builder.header(name, value);
-                continue;
-            }
-            return Err(StreamableHttpError::ReservedHeaderConflict(
-                name.to_string(),
-            ));
-        }
+        validate_custom_header(&name).map_err(StreamableHttpError::ReservedHeaderConflict)?;
         builder = builder.header(name, value);
     }
     Ok(builder)
@@ -306,66 +281,11 @@ impl StreamableHttpClientTransport<reqwest::Client> {
     }
 }
 
-/// extract scope parameter from WWW-Authenticate header
-fn extract_scope_from_header(header: &str) -> Option<String> {
-    let header_lowercase = header.to_ascii_lowercase();
-    let scope_key = "scope=";
-
-    if let Some(pos) = header_lowercase.find(scope_key) {
-        let start = pos + scope_key.len();
-        let value_slice = &header[start..];
-
-        if let Some(stripped) = value_slice.strip_prefix('"') {
-            if let Some(end_quote) = stripped.find('"') {
-                return Some(stripped[..end_quote].to_string());
-            }
-        } else {
-            let end = value_slice
-                .find(|c: char| c == ',' || c == ';' || c.is_whitespace())
-                .unwrap_or(value_slice.len());
-            if end > 0 {
-                return Some(value_slice[..end].to_string());
-            }
-        }
-    }
-
-    None
-}
-
 #[cfg(test)]
 mod tests {
-    use super::{extract_scope_from_header, parse_json_rpc_error};
+    use super::parse_json_rpc_error;
     use crate::{model::JsonRpcMessage, transport::streamable_http_client::InsufficientScopeError};
 
-    #[test]
-    fn extract_scope_quoted() {
-        let header = r#"Bearer error="insufficient_scope", scope="files:read files:write""#;
-        assert_eq!(
-            extract_scope_from_header(header),
-            Some("files:read files:write".to_string())
-        );
-    }
-
-    #[test]
-    fn extract_scope_unquoted() {
-        let header = r#"Bearer scope=read:data, error="insufficient_scope""#;
-        assert_eq!(
-            extract_scope_from_header(header),
-            Some("read:data".to_string())
-        );
-    }
-
-    #[test]
-    fn extract_scope_missing() {
-        let header = r#"Bearer error="invalid_token""#;
-        assert_eq!(extract_scope_from_header(header), None);
-    }
-
-    #[test]
-    fn extract_scope_empty_header() {
-        assert_eq!(extract_scope_from_header("Bearer"), None);
-    }
-
     #[test]
     fn insufficient_scope_error_can_upgrade() {
         let with_scope = InsufficientScopeError {