Prototype remote MCP stdio transport

Add MCP server environment selection and executor-backed stdio transport for remote MCP servers.

Co-authored-by: Codex <noreply@openai.com>

Author: aibrahim-oai

codex-rs/Cargo.lock

@@ -297,6 +297,7 @@ async fn run_add(config_overrides: &CliConfigOverrides, add_args: AddArgs) -> Re
 
     let new_entry = McpServerConfig {
         transport: transport.clone(),
+        environment: Default::default(),
         enabled: true,
         required: false,
         supports_parallel_tool_calls: false,

codex-rs/cli/src/mcp_cmd.rs

@@ -16,6 +16,7 @@ anyhow = { workspace = true }
 async-channel = { workspace = true }
 codex-async-utils = { workspace = true }
 codex-config = { workspace = true }
+codex-exec-server = { workspace = true }
 codex-login = { workspace = true }
 codex-otel = { workspace = true }
 codex-plugin = { workspace = true }

codex-rs/codex-mcp/Cargo.toml

@@ -269,6 +269,7 @@ fn codex_apps_mcp_server_config(config: &McpConfig, auth: Option<&CodexAuth>) ->
             http_headers,
             env_http_headers: None,
         },
+        environment: Default::default(),
         enabled: true,
         required: false,
         supports_parallel_tool_calls: false,
@@ -354,6 +355,8 @@ pub async fn collect_mcp_snapshot_with_detail(
         submit_id,
         tx_event,
         SandboxPolicy::new_read_only_policy(),
+        None,
+        config.codex_home.clone(),
         config.codex_home.clone(),
         codex_apps_tools_cache_key(auth),
         tool_plugin_provenance,
@@ -420,6 +423,8 @@ pub async fn collect_mcp_server_status_snapshot_with_detail(
         submit_id,
         tx_event,
         SandboxPolicy::new_read_only_policy(),
+        None,
+        config.codex_home.clone(),
         config.codex_home.clone(),
         codex_apps_tools_cache_key(auth),
         tool_plugin_provenance,

codex-rs/codex-mcp/src/mcp/mod.rs

@@ -193,6 +193,7 @@ async fn effective_mcp_servers_preserve_user_servers_and_add_codex_apps() {
                 http_headers: None,
                 env_http_headers: None,
             },
+            environment: Default::default(),
             enabled: true,
             required: false,
             supports_parallel_tool_calls: false,
@@ -215,6 +216,7 @@ async fn effective_mcp_servers_preserve_user_servers_and_add_codex_apps() {
                 http_headers: None,
                 env_http_headers: None,
             },
+            environment: Default::default(),
             enabled: true,
             required: false,
             supports_parallel_tool_calls: false,

codex-rs/codex-mcp/src/mcp/mod_tests.rs

@@ -119,6 +119,7 @@ fn mcp_dependency_to_server_config(
                 http_headers: None,
                 env_http_headers: None,
             },
+            environment: Default::default(),
             enabled: true,
             required: false,
             supports_parallel_tool_calls: false,
@@ -146,6 +147,7 @@ fn mcp_dependency_to_server_config(
                 env_vars: Vec::new(),
                 cwd: None,
             },
+            environment: Default::default(),
             enabled: true,
             required: false,
             supports_parallel_tool_calls: false,

codex-rs/codex-mcp/src/mcp/skill_dependencies.rs

@@ -39,6 +39,7 @@ fn collect_missing_respects_canonical_installed_key() {
                 http_headers: None,
                 env_http_headers: None,
             },
+            environment: Default::default(),
             enabled: true,
             required: false,
             supports_parallel_tool_calls: false,
@@ -90,6 +91,7 @@ fn collect_missing_dedupes_by_canonical_key_but_preserves_original_name() {
                 http_headers: None,
                 env_http_headers: None,
             },
+            environment: Default::default(),
             enabled: true,
             required: false,
             supports_parallel_tool_calls: false,

codex-rs/codex-mcp/src/mcp/skill_dependencies_tests.rs

@@ -35,7 +35,9 @@ use async_channel::Sender;
 use codex_async_utils::CancelErr;
 use codex_async_utils::OrCancelExt;
 use codex_config::Constrained;
+use codex_config::McpServerEnvironment;
 use codex_config::types::OAuthCredentialsStoreMode;
+use codex_exec_server::Environment;
 use codex_protocol::ToolName;
 use codex_protocol::approvals::ElicitationRequest;
 use codex_protocol::approvals::ElicitationRequestEvent;
@@ -50,8 +52,11 @@ use codex_protocol::protocol::McpStartupStatus;
 use codex_protocol::protocol::McpStartupUpdateEvent;
 use codex_protocol::protocol::SandboxPolicy;
 use codex_rmcp_client::ElicitationResponse;
+use codex_rmcp_client::ExecutorStdioTransportRuntime;
+use codex_rmcp_client::LocalStdioTransportRuntime;
 use codex_rmcp_client::RmcpClient;
 use codex_rmcp_client::SendElicitation;
+use codex_rmcp_client::StdioTransportRuntime;
 use futures::future::BoxFuture;
 use futures::future::FutureExt;
 use futures::future::Shared;
@@ -470,6 +475,24 @@ impl ManagedClient {
     }
 }
 
+/// Builds the stdio runtime for MCP servers that run in the executor
+/// environment.
+///
+/// The connection manager only decides placement. The returned trait object
+/// hides the implementation detail that remote stdio is backed by
+/// `process/start` plus process read/write calls, while local stdio is backed by
+/// a direct child process.
+fn build_remote_stdio_runtime(
+    environment: Option<Arc<Environment>>,
+    session_cwd: PathBuf,
+) -> Option<Arc<dyn StdioTransportRuntime>> {
+    let environment = environment?;
+    Some(Arc::new(ExecutorStdioTransportRuntime::new(
+        environment.get_exec_backend(),
+        session_cwd,
+    )))
+}
+
 #[derive(Clone)]
 struct AsyncManagedClient {
     client: Shared<BoxFuture<'static, Result<ManagedClient, StartupOutcomeError>>>,
@@ -491,6 +514,7 @@ impl AsyncManagedClient {
         elicitation_requests: ElicitationRequestManager,
         codex_apps_tools_cache_context: Option<CodexAppsToolsCacheContext>,
         tool_plugin_provenance: Arc<ToolPluginProvenance>,
+        remote_stdio_runtime: Option<Arc<dyn StdioTransportRuntime>>,
     ) -> Self {
         let tool_filter = ToolFilter::from_config(&config);
         let startup_snapshot = load_startup_cached_codex_apps_tools_snapshot(
@@ -507,8 +531,15 @@ impl AsyncManagedClient {
                     return Err(error.into());
                 }
 
-                let client =
-                    Arc::new(make_rmcp_client(&server_name, config.transport, store_mode).await?);
+                let client = Arc::new(
+                    make_rmcp_client(
+                        &server_name,
+                        config.clone(),
+                        store_mode,
+                        remote_stdio_runtime,
+                    )
+                    .await?,
+                );
                 match start_server_task(
                     server_name,
                     client,
@@ -708,6 +739,8 @@ impl McpConnectionManager {
         submit_id: String,
         tx_event: Sender<Event>,
         initial_sandbox_policy: SandboxPolicy,
+        environment: Option<Arc<Environment>>,
+        remote_stdio_cwd: PathBuf,
         codex_home: PathBuf,
         codex_apps_tools_cache_key: CodexAppsToolsCacheKey,
         tool_plugin_provenance: ToolPluginProvenance,
@@ -720,6 +753,7 @@ impl McpConnectionManager {
             ElicitationRequestManager::new(approval_policy.value(), initial_sandbox_policy);
         let tool_plugin_provenance = Arc::new(tool_plugin_provenance);
         let startup_submit_id = submit_id.clone();
+        let remote_stdio_runtime = build_remote_stdio_runtime(environment, remote_stdio_cwd);
         let mcp_servers = mcp_servers.clone();
         for (server_name, cfg) in mcp_servers.into_iter().filter(|(_, cfg)| cfg.enabled) {
             if let Some(origin) = transport_origin(&cfg.transport) {
@@ -752,6 +786,7 @@ impl McpConnectionManager {
                 elicitation_requests.clone(),
                 codex_apps_tools_cache_context,
                 Arc::clone(&tool_plugin_provenance),
+                remote_stdio_runtime.clone(),
             );
             clients.insert(server_name.clone(), async_managed_client.clone());
             let tx_event = tx_event.clone();
@@ -1481,9 +1516,16 @@ struct StartServerTaskParams {
 
 async fn make_rmcp_client(
     server_name: &str,
-    transport: McpServerTransportConfig,
+    config: McpServerConfig,
     store_mode: OAuthCredentialsStoreMode,
+    remote_stdio_runtime: Option<Arc<dyn StdioTransportRuntime>>,
 ) -> Result<RmcpClient, StartupOutcomeError> {
+    let McpServerConfig {
+        transport,
+        environment,
+        ..
+    } = config;
+
     match transport {
         McpServerTransportConfig::Stdio {
             command,
@@ -1499,7 +1541,22 @@ async fn make_rmcp_client(
                     .map(|(key, value)| (key.into(), value.into()))
                     .collect::<HashMap<_, _>>()
             });
-            RmcpClient::new_stdio_client(command_os, args_os, env_os, &env_vars, cwd)
+            let runtime = match environment {
+                McpServerEnvironment::Local => {
+                    Arc::new(LocalStdioTransportRuntime) as Arc<dyn StdioTransportRuntime>
+                }
+                McpServerEnvironment::Remote => remote_stdio_runtime.ok_or_else(|| {
+                    StartupOutcomeError::from(anyhow!(
+                        "remote MCP server `{server_name}` requires an executor environment"
+                    ))
+                })?,
+            };
+
+            // `RmcpClient` always sees an MCP stdio transport. The runtime
+            // trait hides whether that transport was created by spawning a
+            // local child process or by asking the executor to start the child
+            // and stream its stdin/stdout bytes over the process API.
+            RmcpClient::new_stdio_client(command_os, args_os, env_os, &env_vars, cwd, runtime)
                 .await
                 .map_err(|err| StartupOutcomeError::from(anyhow!(err)))
         }
@@ -1508,23 +1565,34 @@ async fn make_rmcp_client(
             http_headers,
             env_http_headers,
             bearer_token_env_var,
-        } => {
-            let resolved_bearer_token =
-                match resolve_bearer_token(server_name, bearer_token_env_var.as_deref()) {
-                    Ok(token) => token,
-                    Err(error) => return Err(error.into()),
-                };
-            RmcpClient::new_streamable_http_client(
-                server_name,
-                &url,
-                resolved_bearer_token,
-                http_headers,
-                env_http_headers,
-                store_mode,
-            )
-            .await
-            .map_err(StartupOutcomeError::from)
-        }
+        } => match environment {
+            McpServerEnvironment::Local => {
+                // Local streamable HTTP remains the existing reqwest path from
+                // the orchestrator process.
+                let resolved_bearer_token =
+                    match resolve_bearer_token(server_name, bearer_token_env_var.as_deref()) {
+                        Ok(token) => token,
+                        Err(error) => return Err(error.into()),
+                    };
+                RmcpClient::new_streamable_http_client(
+                    server_name,
+                    &url,
+                    resolved_bearer_token,
+                    http_headers,
+                    env_http_headers,
+                    store_mode,
+                )
+                .await
+                .map_err(StartupOutcomeError::from)
+            }
+            McpServerEnvironment::Remote => Err(StartupOutcomeError::from(anyhow!(
+                // Remote HTTP needs the future low-level executor
+                // `network/request` API so reqwest runs on the executor side.
+                // Do not fall back to local HTTP here; the config explicitly
+                // asked for remote placement.
+                "remote streamable HTTP MCP server `{server_name}` is not implemented yet"
+            ))),
+        },
     }
 }
 

codex-rs/codex-mcp/src/mcp_connection_manager.rs

@@ -792,6 +792,7 @@ fn mcp_init_error_display_prompts_for_github_pat() {
                 http_headers: None,
                 env_http_headers: None,
             },
+            environment: Default::default(),
             enabled: true,
             required: false,
             supports_parallel_tool_calls: false,
@@ -842,6 +843,7 @@ fn mcp_init_error_display_reports_generic_errors() {
                 http_headers: None,
                 env_http_headers: None,
             },
+            environment: Default::default(),
             enabled: true,
             required: false,
             supports_parallel_tool_calls: false,

codex-rs/codex-mcp/src/mcp_connection_manager_tests.rs

@@ -66,6 +66,7 @@ pub use mcp_edit::load_global_mcp_servers;
 pub use mcp_types::AppToolApproval;
 pub use mcp_types::McpServerConfig;
 pub use mcp_types::McpServerDisabledReason;
+pub use mcp_types::McpServerEnvironment;
 pub use mcp_types::McpServerToolConfig;
 pub use mcp_types::McpServerTransportConfig;
 pub use mcp_types::RawMcpServerConfig;