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

[wpfleger96]

Adds UnixSocketHttpClient, a new StreamableHttpClient implementation that routes MCP HTTP traffic through a Unix domain socket using hyper + tokio::net::UnixStream, gated behind the transport-streamable-http-client-unix-socket feature.

MCP hosts running in Kubernetes environments with Envoy sidecars can't use TCP/DNS because outbound traffic must go through the sidecar proxy, which exposes an abstract Unix socket (e.g., @egress.sock). This unblocks any rmcp-based MCP host from connecting through a service mesh sidecar by setting the socket path at transport construction time. The goose equivalent lives in block/goose#7631 and will be replaced with this once merged.

• Adds UnixSocketHttpClient with new(socket_path, uri) constructor and from_unix_socket / from_unix_socket_with_config convenience constructors on StreamableHttpClientTransport
• Supports Linux abstract sockets (@name → \0name) via spawn_blocking + std::os::unix::net since tokio::net::UnixStream lacks connect_addr; filesystem sockets work on all Unix targets
• Extracts RESERVED_HEADERS, validate_custom_header, and extract_scope_from_header from reqwest/streamable_http_client.rs into common/http_header.rs so both HTTP client implementations share a single source of truth for header policy
• Integration tests bind an axum MCP server to a real UnixListener and exercise handshake, custom header forwarding, and the convenience constructor

[michaelneale]

I think it’s a great idea. Always like stdio when you could use it and sockets have a lot of the same security benefits

[wpfleger96]

@michaelneale thanks for the approval, looks like I need another one after fixing CI failures 😅

[jokemanfire]

It's in example here. I don't know we need to wrap it , or just see this example. The abstract of transport is enough now?

[wpfleger96]

👋 hey @jokemanfire I think the example you linked is actually a different use case than what this PR is trying to solve. It looks like that example uses a raw UnixStream as a byte-stream transport (JSON-RPC directly over the socket). That works when the MCP server itself listens on a Unix socket.

This PR solves a slightly different problem: routing Streamable HTTP traffic through a Unix domain socket, where the socket is a sidecar proxy (e.g., Envoy in Kubernetes). The client still needs to speak HTTP/1.1 with proper Host headers, status code handling, SSE streaming, auth headers, etc., which is why we need an HTTP client (hyper) layered over the UnixStream, rather than using it as a raw byte transport.

This is coming from a specific need I have in goose: I opened block/goose#7631 which adds Unix socket transport so MCP extensions can connect through Envoy sidecars in our Kubernetes environment, where DNS only resolves via the proxy. That PR in goose currently creates its own UnixSocketHttpClient directly, but I created this PR based on feedback on that one so that any MCP client that uses rmcp and needs to route MCP requests over UDS can benefit from this work not just goose

[wpfleger96]

👋 @michaelneale @jamadeo @DaleSeo would appreciate a review here if any of you have a moment!

[DaleSeo]

Hi @wpfleger96, could you please look into the failing tests in CI? Thanks!

[jamadeo]

What about using a reqwest client configured with a unix socket?

https://docs.rs/reqwest/latest/reqwest/struct.ClientBuilder.html#method.unix_socket

this can then be used with

rust-sdk/crates/rmcp/src/transport/streamable_http_client.rs

Line 1038 in 55b478b

pub fn with_client(client: C, config: StreamableHttpClientTransportConfig) -> Self {

as long as you have the reqwest feature

[wpfleger96]

@DaleSeo just pushed the fix for failing tests if I could get another approval to let the checks run again!

[wpfleger96]

@jamadeo the reason I went with a separate UnixSocketHttpClient is Linux abstract (non filesystem) Unix socket support - these live in a kernel namespace instead of the filesystem, which is how Envoy sidecars typically expose their proxy in K8s pods. reqwest::ClientBuilder::unix_socket() does work for filesystem Unix sockets and users who already have reqwest enabled can use that today with StreamableHttpClientTransport::with_client(), but for abstract sockets you'd have to manually construct an OsString with a leading null byte:

let mut bytes: Vec<u8> = vec![0];
bytes.extend_from_slice(b"egress.sock");
let path = PathBuf::from(OsString::from_vec(bytes));
let client = reqwest::Client::builder().unix_socket(path).build()?;

vs this PR:

let transport = StreamableHttpClientTransport::from_unix_socket("@egress.sock", "http://mcp-server.internal/mcp");

the @ prefix opts into the abstract socket namespace so without it the path is treated as a regular filesystem socket, and follows the same convention used by socat/ss/systemd

this feature is also independent of the reqwest feature flag, it only needs hyper + tokio

what do you think?

[jamadeo]

Couldn't it just be

let client = reqwest::Client::builder().unix_socket("\0egress.sock").build()?;

?

Or even if not, 4 lines does still seem pretty simple. It is nice that this doesn't require reqwest though.

[wpfleger96]

ahhh yeah great point, I think you're right this would work:

let client = reqwest::Client::builder().unix_socket("\0egress.sock").build()?;

I didn't catch the faulty assumption about null bytes in strings, seems like this is fine in Rust (but not C)

so the main value of this PR at this point is really the reqwest-independence, plus any rmcp-based MCP host gets abstract socket support out of the box rather than implementing their own Unix socket HTTP clients