[MCP] Add experimental support for streamable HTTP MCP servers (#4317)

This PR adds support for streamable HTTP MCP servers when the
`experimental_use_rmcp_client` is enabled.

To set one up, simply add a new mcp server config with the url:
```
[mcp_servers.figma]
url = "http://127.0.0.1:3845/mcp"
```

It also supports an optional `bearer_token` which will be provided in an
authorization header. The full oauth flow is not supported yet.

The config parsing will throw if it detects that the user mixed and
matched config fields (like command + bearer token or url + env).

The best way to review it is to review `core/src` and then
`rmcp-client/src/rmcp_client.rs` first. The rest is tests and
propagating the `Transport` struct around the codebase.

Example with the Figma MCP:
<img width="5084" height="1614" alt="CleanShot 2025-09-26 at 13 35 40"
src="https://github.com/user-attachments/assets/eaf2771e-df3e-4300-816b-184d7dec5a28"
/>

codex-rs/rmcp-client/src/bin/test_stdio_server.rs

@@ -0,0 +1,142 @@
+use std::borrow::Cow;
+use std::collections::HashMap;
+use std::sync::Arc;
+
+use rmcp::ErrorData as McpError;
+use rmcp::ServiceExt;
+use rmcp::handler::server::ServerHandler;
+use rmcp::model::CallToolRequestParam;
+use rmcp::model::CallToolResult;
+use rmcp::model::JsonObject;
+use rmcp::model::ListToolsResult;
+use rmcp::model::PaginatedRequestParam;
+use rmcp::model::ServerCapabilities;
+use rmcp::model::ServerInfo;
+use rmcp::model::Tool;
+use serde::Deserialize;
+use serde_json::json;
+use tokio::task;
+
+#[derive(Clone)]
+struct TestToolServer {
+    tools: Arc<Vec<Tool>>,
+}
+pub fn stdio() -> (tokio::io::Stdin, tokio::io::Stdout) {
+    (tokio::io::stdin(), tokio::io::stdout())
+}
+impl TestToolServer {
+    fn new() -> Self {
+        let tools = vec![Self::echo_tool()];
+        Self {
+            tools: Arc::new(tools),
+        }
+    }
+
+    fn echo_tool() -> Tool {
+        #[expect(clippy::expect_used)]
+        let schema: JsonObject = serde_json::from_value(json!({
+            "type": "object",
+            "properties": {
+                "message": { "type": "string" },
+                "env_var": { "type": "string" }
+            },
+            "required": ["message"],
+            "additionalProperties": false
+        }))
+        .expect("echo tool schema should deserialize");
+
+        Tool::new(
+            Cow::Borrowed("echo"),
+            Cow::Borrowed("Echo back the provided message and include environment data."),
+            Arc::new(schema),
+        )
+    }
+}
+
+#[derive(Deserialize)]
+struct EchoArgs {
+    message: String,
+    #[allow(dead_code)]
+    env_var: Option<String>,
+}
+
+impl ServerHandler for TestToolServer {
+    fn get_info(&self) -> ServerInfo {
+        ServerInfo {
+            capabilities: ServerCapabilities::builder()
+                .enable_tools()
+                .enable_tool_list_changed()
+                .build(),
+            ..ServerInfo::default()
+        }
+    }
+
+    fn list_tools(
+        &self,
+        _request: Option<PaginatedRequestParam>,
+        _context: rmcp::service::RequestContext<rmcp::service::RoleServer>,
+    ) -> impl std::future::Future<Output = Result<ListToolsResult, McpError>> + Send + '_ {
+        let tools = self.tools.clone();
+        async move {
+            Ok(ListToolsResult {
+                tools: (*tools).clone(),
+                next_cursor: None,
+            })
+        }
+    }
+
+    async fn call_tool(
+        &self,
+        request: CallToolRequestParam,
+        _context: rmcp::service::RequestContext<rmcp::service::RoleServer>,
+    ) -> Result<CallToolResult, McpError> {
+        match request.name.as_ref() {
+            "echo" => {
+                let args: EchoArgs = match request.arguments {
+                    Some(arguments) => serde_json::from_value(serde_json::Value::Object(
+                        arguments.into_iter().collect(),
+                    ))
+                    .map_err(|err| McpError::invalid_params(err.to_string(), None))?,
+                    None => {
+                        return Err(McpError::invalid_params(
+                            "missing arguments for echo tool",
+                            None,
+                        ));
+                    }
+                };
+
+                let env_snapshot: HashMap<String, String> = std::env::vars().collect();
+                let structured_content = json!({
+                    "echo": format!("ECHOING: {}", args.message),
+                    "env": env_snapshot.get("MCP_TEST_VALUE"),
+                });
+
+                Ok(CallToolResult {
+                    content: Vec::new(),
+                    structured_content: Some(structured_content),
+                    is_error: Some(false),
+                    meta: None,
+                })
+            }
+            other => Err(McpError::invalid_params(
+                format!("unknown tool: {other}"),
+                None,
+            )),
+        }
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    eprintln!("starting rmcp test server");
+    // Run the server with STDIO transport. If the client disconnects we simply
+    // bubble up the error so the process exits.
+    let service = TestToolServer::new();
+    let running = service.serve(stdio()).await?;
+
+    // Wait for the client to finish interacting with the server.
+    running.waiting().await?;
+    // Drain background tasks to ensure clean shutdown.
+    task::yield_now().await;
+    Ok(())
+}

codex-rs/rmcp-client/src/bin/test_streamable_http_server.rs

@@ -0,0 +1,167 @@
+use std::borrow::Cow;
+use std::collections::HashMap;
+use std::io::ErrorKind;
+use std::net::SocketAddr;
+use std::sync::Arc;
+
+use axum::Router;
+use rmcp::ErrorData as McpError;
+use rmcp::handler::server::ServerHandler;
+use rmcp::model::CallToolRequestParam;
+use rmcp::model::CallToolResult;
+use rmcp::model::JsonObject;
+use rmcp::model::ListToolsResult;
+use rmcp::model::PaginatedRequestParam;
+use rmcp::model::ServerCapabilities;
+use rmcp::model::ServerInfo;
+use rmcp::model::Tool;
+use rmcp::transport::StreamableHttpServerConfig;
+use rmcp::transport::StreamableHttpService;
+use rmcp::transport::streamable_http_server::session::local::LocalSessionManager;
+use serde::Deserialize;
+use serde_json::json;
+use tokio::task;
+
+#[derive(Clone)]
+struct TestToolServer {
+    tools: Arc<Vec<Tool>>,
+}
+
+impl TestToolServer {
+    fn new() -> Self {
+        let tools = vec![Self::echo_tool()];
+        Self {
+            tools: Arc::new(tools),
+        }
+    }
+
+    fn echo_tool() -> Tool {
+        #[expect(clippy::expect_used)]
+        let schema: JsonObject = serde_json::from_value(json!({
+            "type": "object",
+            "properties": {
+                "message": { "type": "string" },
+                "env_var": { "type": "string" }
+            },
+            "required": ["message"],
+            "additionalProperties": false
+        }))
+        .expect("echo tool schema should deserialize");
+
+        Tool::new(
+            Cow::Borrowed("echo"),
+            Cow::Borrowed("Echo back the provided message and include environment data."),
+            Arc::new(schema),
+        )
+    }
+}
+
+#[derive(Deserialize)]
+struct EchoArgs {
+    message: String,
+    #[allow(dead_code)]
+    env_var: Option<String>,
+}
+
+impl ServerHandler for TestToolServer {
+    fn get_info(&self) -> ServerInfo {
+        ServerInfo {
+            capabilities: ServerCapabilities::builder()
+                .enable_tools()
+                .enable_tool_list_changed()
+                .build(),
+            ..ServerInfo::default()
+        }
+    }
+
+    fn list_tools(
+        &self,
+        _request: Option<PaginatedRequestParam>,
+        _context: rmcp::service::RequestContext<rmcp::service::RoleServer>,
+    ) -> impl std::future::Future<Output = Result<ListToolsResult, McpError>> + Send + '_ {
+        let tools = self.tools.clone();
+        async move {
+            Ok(ListToolsResult {
+                tools: (*tools).clone(),
+                next_cursor: None,
+            })
+        }
+    }
+
+    async fn call_tool(
+        &self,
+        request: CallToolRequestParam,
+        _context: rmcp::service::RequestContext<rmcp::service::RoleServer>,
+    ) -> Result<CallToolResult, McpError> {
+        match request.name.as_ref() {
+            "echo" => {
+                let args: EchoArgs = match request.arguments {
+                    Some(arguments) => serde_json::from_value(serde_json::Value::Object(
+                        arguments.into_iter().collect(),
+                    ))
+                    .map_err(|err| McpError::invalid_params(err.to_string(), None))?,
+                    None => {
+                        return Err(McpError::invalid_params(
+                            "missing arguments for echo tool",
+                            None,
+                        ));
+                    }
+                };
+
+                let env_snapshot: HashMap<String, String> = std::env::vars().collect();
+                let structured_content = json!({
+                    "echo": format!("ECHOING: {}", args.message),
+                    "env": env_snapshot.get("MCP_TEST_VALUE"),
+                });
+
+                Ok(CallToolResult {
+                    content: Vec::new(),
+                    structured_content: Some(structured_content),
+                    is_error: Some(false),
+                    meta: None,
+                })
+            }
+            other => Err(McpError::invalid_params(
+                format!("unknown tool: {other}"),
+                None,
+            )),
+        }
+    }
+}
+
+fn parse_bind_addr() -> Result<SocketAddr, Box<dyn std::error::Error>> {
+    let default_addr = "127.0.0.1:3920";
+    let bind_addr = std::env::var("MCP_STREAMABLE_HTTP_BIND_ADDR")
+        .or_else(|_| std::env::var("BIND_ADDR"))
+        .unwrap_or_else(|_| default_addr.to_string());
+    Ok(bind_addr.parse()?)
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let bind_addr = parse_bind_addr()?;
+    let listener = match tokio::net::TcpListener::bind(&bind_addr).await {
+        Ok(listener) => listener,
+        Err(err) if err.kind() == ErrorKind::PermissionDenied => {
+            eprintln!(
+                "failed to bind to {bind_addr}: {err}. make sure the process has network access"
+            );
+            return Ok(());
+        }
+        Err(err) => return Err(err.into()),
+    };
+    eprintln!("starting rmcp streamable http test server on http://{bind_addr}/mcp");
+
+    let router = Router::new().nest_service(
+        "/mcp",
+        StreamableHttpService::new(
+            || Ok(TestToolServer::new()),
+            Arc::new(LocalSessionManager::default()),
+            StreamableHttpServerConfig::default(),
+        ),
+    );
+
+    axum::serve(listener, router).await?;
+    task::yield_now().await;
+    Ok(())
+}

codex-rs/rmcp-client/src/rmcp_client.rs

@@ -7,6 +7,7 @@ use std::time::Duration;
 
 use anyhow::Result;
 use anyhow::anyhow;
+use futures::FutureExt;
 use mcp_types::CallToolRequestParams;
 use mcp_types::CallToolResult;
 use mcp_types::InitializeRequestParams;
@@ -19,7 +20,9 @@ use rmcp::model::PaginatedRequestParam;
 use rmcp::service::RoleClient;
 use rmcp::service::RunningService;
 use rmcp::service::{self};
+use rmcp::transport::StreamableHttpClientTransport;
 use rmcp::transport::child_process::TokioChildProcess;
+use rmcp::transport::streamable_http_client::StreamableHttpClientTransportConfig;
 use tokio::io::AsyncBufReadExt;
 use tokio::io::BufReader;
 use tokio::process::Command;
@@ -35,9 +38,14 @@ use crate::utils::convert_to_rmcp;
 use crate::utils::create_env_for_mcp_server;
 use crate::utils::run_with_timeout;
 
+enum PendingTransport {
+    ChildProcess(TokioChildProcess),
+    StreamableHttp(StreamableHttpClientTransport<reqwest::Client>),
+}
+
 enum ClientState {
     Connecting {
-        transport: Option<TokioChildProcess>,
+        transport: Option<PendingTransport>,
     },
     Ready {
         service: Arc<RunningService<RoleClient, LoggingClientHandler>>,
@@ -90,7 +98,22 @@ impl RmcpClient {
 
         Ok(Self {
             state: Mutex::new(ClientState::Connecting {
-                transport: Some(transport),
+                transport: Some(PendingTransport::ChildProcess(transport)),
+            }),
+        })
+    }
+
+    pub fn new_streamable_http_client(url: String, bearer_token: Option<String>) -> Result<Self> {
+        let mut config = StreamableHttpClientTransportConfig::with_uri(url);
+        if let Some(token) = bearer_token {
+            config = config.auth_header(format!("Bearer {token}"));
+        }
+
+        let transport = StreamableHttpClientTransport::from_config(config);
+
+        Ok(Self {
+            state: Mutex::new(ClientState::Connecting {
+                transport: Some(PendingTransport::StreamableHttp(transport)),
             }),
         })
     }
@@ -116,7 +139,14 @@ impl RmcpClient {
 
         let client_info = convert_to_rmcp::<_, InitializeRequestParam>(params.clone())?;
         let client_handler = LoggingClientHandler::new(client_info);
-        let service_future = service::serve_client(client_handler, transport);
+        let service_future = match transport {
+            PendingTransport::ChildProcess(transport) => {
+                service::serve_client(client_handler.clone(), transport).boxed()
+            }
+            PendingTransport::StreamableHttp(transport) => {
+                service::serve_client(client_handler, transport).boxed()
+            }
+        };
 
         let service = match timeout {
             Some(duration) => time::timeout(duration, service_future)