feat(extensions): add Unix socket transport for StreamableHttp extensions

In some service mesh environments (e.g. Kubernetes with an Envoy sidecar),
all outbound HTTP must route through a local proxy rather than making direct
TCP connections to remote endpoints. Adds an optional `socket` field to
`ExtensionConfig::StreamableHttp` so connections can be routed through a
Unix domain socket, with `uri` preserved as the HTTP Host header and path.

Implements `rmcp::StreamableHttpClient` for a new `UnixSocketHttpClient`
using hyper + `tokio::net::UnixStream`, plugging into rmcp's existing
`StreamableHttpClientTransport::with_client()` extension point. Supports
both filesystem sockets and Linux abstract sockets (`@` prefix). Auth at
the transport layer (e.g. mutual TLS via the sidecar) makes OAuth retry
unnecessary on this path.

Configured via `socket: "@egress.sock"` alongside the existing `uri` field
in YAML config or the goosed API — no change for TCP-only deployments.

Author: wpfleger96

Cargo.lock

@@ -86,6 +86,7 @@ fn mcp_server_to_extension_config(mcp_server: McpServer) -> Result<ExtensionConf
                 .into_iter()
                 .map(|h| (h.name, h.value))
                 .collect(),
+            socket: None,
             timeout: None,
             bundled: Some(false),
             available_tools: vec![],
@@ -1403,6 +1404,7 @@ mod tests {
                 "Authorization".into(),
                 "Bearer ghp_xxxxxxxxxxxx".into()
             )]),
+            socket: None,
             timeout: None,
             bundled: Some(false),
             available_tools: vec![],

crates/goose-acp/src/server.rs

@@ -1140,6 +1140,7 @@ fn configure_streamable_http_extension() -> anyhow::Result<()> {
             envs: Envs::new(envs),
             env_keys,
             headers,
+            socket: None,
             description,
             timeout: Some(timeout),
             bundled: None,

crates/goose-cli/src/commands/configure.rs

@@ -150,6 +150,7 @@ mod tests {
                     bundled: None,
                     available_tools: Vec::new(),
                     headers: HashMap::new(),
+                    socket: None,
                 },
                 ExtensionConfig::Stdio {
                     name: "slack-mcp".to_string(),
@@ -246,6 +247,7 @@ mod tests {
                     bundled: None,
                     available_tools: Vec::new(),
                     headers: HashMap::new(),
+                    socket: None,
                 },
                 ExtensionConfig::Stdio {
                     name: "service-b".to_string(),
@@ -305,6 +307,7 @@ mod tests {
                 bundled: None,
                 available_tools: Vec::new(),
                 headers: HashMap::new(),
+                socket: None,
             }]),
             sub_recipes: Some(vec![SubRecipe {
                 name: "child-recipe".to_string(),

crates/goose-cli/src/recipes/secret_discovery.rs

@@ -337,6 +337,7 @@ impl CliSession {
             envs: Envs::new(HashMap::new()),
             env_keys: Vec::new(),
             headers: HashMap::new(),
+            socket: None,
             description: goose::config::DEFAULT_EXTENSION_DESCRIPTION.to_string(),
             timeout: Some(timeout),
             bundled: None,
@@ -2034,6 +2035,7 @@ mod tests {
             envs: Envs::default(),
             env_keys: vec![],
             headers: HashMap::new(),
+            socket: None,
             description: goose::config::DEFAULT_EXTENSION_DESCRIPTION.to_string(),
             timeout: Some(300),
             bundled: None,
@@ -2049,6 +2051,7 @@ mod tests {
             envs: Envs::default(),
             env_keys: vec![],
             headers: HashMap::new(),
+            socket: None,
             description: goose::config::DEFAULT_EXTENSION_DESCRIPTION.to_string(),
             timeout: Some(300),
             bundled: None,
@@ -2064,6 +2067,7 @@ mod tests {
             envs: Envs::default(),
             env_keys: vec![],
             headers: HashMap::new(),
+            socket: None,
             description: goose::config::DEFAULT_EXTENSION_DESCRIPTION.to_string(),
             timeout: Some(300),
             bundled: None,

crates/goose-cli/src/session/mod.rs

@@ -141,6 +141,15 @@ pulldown-cmark = "0.13.0"
 llama-cpp-2 = { git = "https://github.com/jh-block/llama-cpp-rs.git", branch = "goose-patches", features = ["sampler"] }
 encoding_rs = "0.8.35"
 
+# Unix domain socket HTTP transport for StreamableHttp extensions
+[target.'cfg(unix)'.dependencies]
+hyper = { version = "1", features = ["client", "http1"] }
+hyper-util = { version = "0.1", features = ["tokio"] }
+http-body-util = "0.1"
+sse-stream = "0.2"
+bytes = { workspace = true }
+http = { workspace = true }
+
 [target.'cfg(target_os = "windows")'.dependencies]
 winapi = { version = "0.3", features = ["wincred"] }
 

crates/goose/Cargo.toml

@@ -230,6 +230,11 @@ pub enum ExtensionConfig {
         env_keys: Vec<String>,
         #[serde(default)]
         headers: HashMap<String, String>,
+        /// Unix domain socket path to route HTTP through (e.g. "@egress.sock" for Envoy sidecar).
+        /// When set, the physical connection goes through this socket while `uri` is used for the
+        /// HTTP Host header and path. Useful in K8s environments where DNS only resolves via Envoy.
+        #[serde(default)]
+        socket: Option<String>,
         // NOTE: set timeout to be optional for compatibility.
         // However, new configurations should include this field.
         timeout: Option<u64>,
@@ -301,6 +306,7 @@ impl ExtensionConfig {
             envs: Envs::default(),
             env_keys: Vec::new(),
             headers: HashMap::new(),
+            socket: None,
             description: description.into(),
             timeout: Some(timeout.into()),
             bundled: None,
@@ -455,6 +461,7 @@ impl ExtensionConfig {
                 envs,
                 env_keys,
                 headers,
+                socket,
                 timeout,
                 bundled,
                 available_tools,
@@ -474,6 +481,7 @@ impl ExtensionConfig {
                     envs: Envs::new(merged),
                     env_keys: vec![],
                     headers,
+                    socket,
                     timeout,
                     bundled,
                     available_tools,
@@ -490,9 +498,12 @@ impl std::fmt::Display for ExtensionConfig {
             ExtensionConfig::Sse { name, .. } => {
                 write!(f, "SSE({}: unsupported)", name)
             }
-            ExtensionConfig::StreamableHttp { name, uri, .. } => {
-                write!(f, "StreamableHttp({}: {})", name, uri)
-            }
+            ExtensionConfig::StreamableHttp {
+                name, uri, socket, ..
+            } => match socket {
+                Some(s) => write!(f, "StreamableHttp({}: {} via {})", name, uri, s),
+                None => write!(f, "StreamableHttp({}: {})", name, uri),
+            },
             ExtensionConfig::Stdio {
                 name, cmd, args, ..
             } => {
@@ -665,6 +676,7 @@ available_tools: []
             )]
             .into_iter()
             .collect(),
+            socket: None,
             timeout: None,
             bundled: None,
             available_tools: vec![],
@@ -685,6 +697,7 @@ available_tools: []
             )]
             .into_iter()
             .collect(),
+            socket: None,
             timeout: None,
             bundled: None,
             available_tools: vec![],
@@ -758,6 +771,7 @@ available_tools: []
             )]
             .into_iter()
             .collect(),
+            socket: None,
             timeout: None,
             bundled: None,
             available_tools: vec![],
@@ -775,6 +789,7 @@ available_tools: []
             headers: [("Authorization".to_string(), "Bearer secret_value".to_string())]
                 .into_iter()
                 .collect(),
+            socket: None,
             timeout: None,
             bundled: None,
             available_tools: vec![],
@@ -825,4 +840,64 @@ available_tools: []
         cfg.set("MY_SECRET", &"secret_value", true).unwrap();
         assert_eq!(config.resolve(&cfg).await.unwrap(), expected);
     }
+
+    #[test]
+    fn test_deserialize_streamable_http_with_socket() {
+        let config: ExtensionConfig = serde_yaml::from_str(
+            "type: streamable_http\nname: ai-app-info\ndescription: test\nuri: http://example.com/mcp\nsocket: \"@egress.sock\"\n",
+        )
+        .unwrap();
+        if let ExtensionConfig::StreamableHttp { socket, .. } = config {
+            assert_eq!(socket, Some("@egress.sock".to_string()));
+        } else {
+            panic!("unexpected variant");
+        }
+    }
+
+    #[test]
+    fn test_deserialize_streamable_http_without_socket() {
+        let config: ExtensionConfig = serde_yaml::from_str(
+            "type: streamable_http\nname: ai-app-info\ndescription: test\nuri: http://example.com/mcp\n",
+        )
+        .unwrap();
+        if let ExtensionConfig::StreamableHttp { socket, .. } = config {
+            assert_eq!(socket, None);
+        } else {
+            panic!("unexpected variant");
+        }
+    }
+
+    #[test]
+    fn test_display_streamable_http_without_socket() {
+        let config = ExtensionConfig::streamable_http(
+            "ai-app-info",
+            "http://example.com/mcp",
+            "test",
+            300u64,
+        );
+        assert_eq!(
+            format!("{config}"),
+            "StreamableHttp(ai-app-info: http://example.com/mcp)"
+        );
+    }
+
+    #[test]
+    fn test_display_streamable_http_with_socket() {
+        let config = ExtensionConfig::StreamableHttp {
+            name: "ai-app-info".to_string(),
+            uri: "http://example.com/mcp".to_string(),
+            description: "test".to_string(),
+            timeout: Some(300),
+            headers: Default::default(),
+            envs: Default::default(),
+            env_keys: vec![],
+            socket: Some("@egress.sock".to_string()),
+            bundled: None,
+            available_tools: vec![],
+        };
+        assert_eq!(
+            format!("{config}"),
+            "StreamableHttp(ai-app-info: http://example.com/mcp via @egress.sock)"
+        );
+    }
 }

crates/goose/src/agents/extension.rs

@@ -393,6 +393,7 @@ pub(crate) fn substitute_env_vars(value: &str, env_map: &HashMap<String, String>
 const GOOSE_USER_AGENT: reqwest::header::HeaderValue =
     reqwest::header::HeaderValue::from_static(concat!("goose/", env!("CARGO_PKG_VERSION")));
 
+#[allow(clippy::too_many_arguments)]
 async fn create_streamable_http_client(
     uri: &str,
     timeout: Option<u64>,
@@ -401,7 +402,29 @@ async fn create_streamable_http_client(
     provider: SharedProvider,
     client_name: String,
     capabilities: GooseMcpClientCapabilities,
+    socket: Option<&str>,
 ) -> ExtensionResult<Box<dyn McpClientTrait>> {
+    #[cfg(unix)]
+    if let Some(socket_path) = socket {
+        return create_unix_socket_http_client(
+            uri,
+            timeout,
+            headers,
+            socket_path,
+            provider,
+            client_name,
+            capabilities,
+        )
+        .await;
+    }
+
+    #[cfg(not(unix))]
+    if socket.is_some() {
+        return Err(ExtensionError::ConfigError(
+            "Unix domain socket transport is not supported on this platform".to_string(),
+        ));
+    }
+
     let mut default_headers = HeaderMap::new();
 
     default_headers.insert(reqwest::header::USER_AGENT, GOOSE_USER_AGENT);
@@ -476,6 +499,64 @@ async fn create_streamable_http_client(
     }
 }
 
+/// Connect to a StreamableHttp MCP server via a Unix domain socket.
+/// OAuth retry is intentionally omitted — auth at the socket layer is typically
+/// handled by the sidecar proxy (e.g., Envoy mTLS) rather than HTTP Bearer tokens.
+#[cfg(unix)]
+async fn create_unix_socket_http_client(
+    uri: &str,
+    timeout: Option<u64>,
+    headers: &HashMap<String, String>,
+    socket_path: &str,
+    provider: SharedProvider,
+    client_name: String,
+    capabilities: GooseMcpClientCapabilities,
+) -> ExtensionResult<Box<dyn McpClientTrait>> {
+    use super::unix_socket_http_client::UnixSocketHttpClient;
+    use http::header::HeaderValue;
+
+    #[cfg(not(target_os = "linux"))]
+    if socket_path.starts_with('@') {
+        return Err(ExtensionError::ConfigError(
+            "Abstract Unix sockets (@-prefixed) are only supported on Linux".to_string(),
+        ));
+    }
+
+    let mut default_headers = std::collections::HashMap::new();
+    default_headers.insert(reqwest::header::USER_AGENT, GOOSE_USER_AGENT);
+    for (key, value) in headers {
+        let name = HeaderName::try_from(key)
+            .map_err(|_| ExtensionError::ConfigError(format!("invalid header: {key}")))?;
+        let val: HeaderValue = value
+            .parse()
+            .map_err(|_| ExtensionError::ConfigError(format!("invalid header value: {key}")))?;
+        default_headers.insert(name, val);
+    }
+
+    let unix_client = UnixSocketHttpClient::new(uri, socket_path, default_headers);
+    let transport = StreamableHttpClientTransport::with_client(
+        unix_client,
+        StreamableHttpClientTransportConfig {
+            uri: uri.into(),
+            ..Default::default()
+        },
+    );
+
+    let timeout_duration =
+        Duration::from_secs(timeout.unwrap_or(crate::config::DEFAULT_EXTENSION_TIMEOUT));
+
+    Ok(Box::new(
+        McpClient::connect(
+            transport,
+            timeout_duration,
+            provider,
+            client_name,
+            capabilities,
+        )
+        .await?,
+    ))
+}
+
 impl ExtensionManager {
     pub fn new(
         provider: SharedProvider,
@@ -556,6 +637,7 @@ impl ExtensionManager {
                 name,
                 envs,
                 env_keys,
+                socket,
                 ..
             } => {
                 let config = Config::global();
@@ -576,6 +658,7 @@ impl ExtensionManager {
                     self.provider.clone(),
                     self.client_name.clone(),
                     capability,
+                    socket.as_deref(),
                 )
                 .await?
             }

crates/goose/src/agents/extension_manager.rs

@@ -20,6 +20,8 @@ pub(crate) mod subagent_handler;
 pub(crate) mod subagent_task_config;
 mod tool_execution;
 pub mod types;
+#[cfg(unix)]
+pub(crate) mod unix_socket_http_client;
 pub mod validate_extensions;
 
 pub use agent::{Agent, AgentConfig, AgentEvent, ExtensionLoadResult, GoosePlatform};