feat: enable Streamable HTTP MCP servers & lazy loading of tools

Author: seratch

codex-rs/Cargo.lock

@@ -312,7 +312,7 @@ You can further customize how Codex runs at the command line using the `--ask-fo
 
 ## mcp_servers
 
-Defines the list of MCP servers that Codex can consult for tool use. Currently, only servers that are launched by executing a program that communicate over stdio are supported. For servers that use the SSE transport, consider an adapter like [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy).
+Defines the list of MCP servers that Codex can consult for tool use. Servers may either be launched as subprocesses that communicate over stdio or accessed via the Streamable HTTP transport.
 
 **Note:** Codex may cache the list of tools and resources from an MCP server so that Codex can include this information in context at startup without spawning all the servers. This is designed to save resources by loading MCP servers lazily.
 
@@ -340,8 +340,15 @@ Should be represented as follows in `~/.codex/config.toml`:
 command = "npx"
 args = ["-y", "mcp-server"]
 env = { "API_KEY" = "value" }
+
+# Streamable HTTP remote servers
+[mcp_servers.my_mcp_sever]
+url = "https://{the-actual-domain-here}/mcp"
+# headers = { Authorization = "Bearer {token}" }
 ```
 
+When you start a new session, it automatically begins fetching the list of tools in the background. If some tools may take a little longer to load, you can run `/mcp` command to confirm everything is ready before sending your prompt.
+
 ## disable_response_storage
 
 Currently, customers whose accounts are set to use Zero Data Retention (ZDR) must set `disable_response_storage` to `true` so that Codex uses an alternative to the Responses API that works with ZDR:

codex-rs/config.md

@@ -532,6 +532,9 @@ impl Session {
             }
         }
 
+        // Kick off background MCP tool initialization/loading without blocking the UI.
+        sess.mcp_connection_manager.refresh_tools_in_background();
+
         Ok((sess, turn_context))
     }
 
@@ -1206,7 +1209,12 @@ async fn submission_loop(
                 let tx_event = sess.tx_event.clone();
                 let sub_id = sub.id.clone();
 
-                // This is a cheap lookup from the connection manager's cache.
+                // Refresh tools on-demand to give users an up-to-date list.
+                // This runs in the foreground for this operation only.
+                if let Err(e) = sess.mcp_connection_manager.refresh_tools().await {
+                    warn!("failed to refresh MCP tools: {e:#}");
+                }
+
                 let tools = sess.mcp_connection_manager.list_all_tools();
                 let event = Event {
                     id: sub_id,
@@ -1486,6 +1494,12 @@ async fn run_turn(
     sub_id: String,
     input: Vec<ResponseItem>,
 ) -> CodexResult<Vec<ProcessedResponseItem>> {
+    // Give MCP tools a brief moment to arrive if background discovery is still running.
+    // This avoids an empty tool list in the first turn right after startup.
+    sess.mcp_connection_manager
+        .wait_for_tools_with_timeout(std::time::Duration::from_millis(800))
+        .await;
+
     let tools = get_openai_tools(
         &turn_context.tools_config,
         Some(sess.mcp_connection_manager.list_all_tools()),

codex-rs/core/src/codex.rs

@@ -10,14 +10,25 @@ use wildmatch::WildMatchPattern;
 use serde::Deserialize;
 
 #[derive(Deserialize, Debug, Clone, PartialEq)]
-pub struct McpServerConfig {
-    pub command: String,
-
-    #[serde(default)]
-    pub args: Vec<String>,
-
-    #[serde(default)]
-    pub env: Option<HashMap<String, String>>,
+#[serde(untagged)]
+pub enum McpServerConfig {
+    /// MCP server launched as a subprocess that communicates over stdio.
+    Stdio {
+        command: String,
+
+        #[serde(default)]
+        args: Vec<String>,
+
+        #[serde(default)]
+        env: Option<HashMap<String, String>>,
+    },
+    /// MCP server reachable via the Streamable HTTP transport.
+    StreamableHttp {
+        url: String,
+
+        #[serde(default)]
+        headers: Option<HashMap<String, String>>,
+    },
 }
 
 #[derive(Deserialize, Debug, Copy, Clone, PartialEq)]