Extract MCP into codex-mcp crate (#15919)

- Split MCP runtime/server code out of `codex-core` into the new
`codex-mcp` crate. New/moved public structs/types include `McpConfig`,
`McpConnectionManager`, `ToolInfo`, `ToolPluginProvenance`,
`CodexAppsToolsCacheKey`, and the `McpManager` API
(`codex_mcp::mcp::McpManager` plus the `codex_core::mcp::McpManager`
wrapper/shim). New/moved functions include `with_codex_apps_mcp`,
`configured_mcp_servers`, `effective_mcp_servers`,
`collect_mcp_snapshot`, `collect_mcp_snapshot_from_manager`,
`qualified_mcp_tool_name_prefix`, and the MCP auth/skill-dependency
helpers. Why: this creates a focused MCP crate boundary and shrinks
`codex-core` without forcing every consumer to migrate in the same PR.

- Move MCP server config schema and persistence into `codex-config`.
New/moved structs/enums include `AppToolApproval`,
`McpServerToolConfig`, `McpServerConfig`, `RawMcpServerConfig`,
`McpServerTransportConfig`, `McpServerDisabledReason`, and
`codex_config::ConfigEditsBuilder`. New/moved functions include
`load_global_mcp_servers` and
`ConfigEditsBuilder::replace_mcp_servers`/`apply`. Why: MCP TOML
parsing/editing is config ownership, and this keeps config
validation/round-tripping (including per-tool approval overrides and
inline bearer-token rejection) in the config crate instead of
`codex-core`.

- Rewire `codex-core`, app-server, and plugin call sites onto the new
crates. Updated `Config::to_mcp_config(&self, plugins_manager)`,
`codex-rs/core/src/mcp.rs`, `codex-rs/core/src/connectors.rs`,
`codex-rs/core/src/codex.rs`,
`CodexMessageProcessor::list_mcp_server_status_task`, and
`utils/plugins/src/mcp_connector.rs` to build/pass the new MCP
config/runtime types. Why: plugin-provided MCP servers still merge with
user-configured servers, and runtime auth (`CodexAuth`) is threaded into
`with_codex_apps_mcp` / `collect_mcp_snapshot` explicitly so `McpConfig`
stays config-only.

codex-rs/Cargo.lock

@@ -1848,6 +1848,7 @@ dependencies = [
  "codex-hooks",
  "codex-instructions",
  "codex-login",
+ "codex-mcp",
  "codex-network-proxy",
  "codex-otel",
  "codex-plugin",
@@ -2260,6 +2261,35 @@ dependencies = [
  "wiremock",
 ]
 
+[[package]]
+name = "codex-mcp"
+version = "0.0.0"
+dependencies = [
+ "anyhow",
+ "async-channel",
+ "codex-async-utils",
+ "codex-config",
+ "codex-login",
+ "codex-otel",
+ "codex-plugin",
+ "codex-protocol",
+ "codex-rmcp-client",
+ "codex-utils-plugins",
+ "futures",
+ "pretty_assertions",
+ "regex-lite",
+ "rmcp",
+ "serde",
+ "serde_json",
+ "sha1",
+ "tempfile",
+ "thiserror 2.0.18",
+ "tokio",
+ "tokio-util",
+ "tracing",
+ "url",
+]
+
 [[package]]
 name = "codex-mcp-server"
 version = "0.0.0"
@@ -2849,6 +2879,7 @@ dependencies = [
 name = "codex-utils-plugins"
 version = "0.0.0"
 dependencies = [
+ "codex-login",
  "serde",
  "serde_json",
  "tempfile",

codex-rs/Cargo.toml

@@ -39,6 +39,7 @@ members = [
     "linux-sandbox",
     "lmstudio",
     "login",
+    "codex-mcp",
     "mcp-server",
     "network-proxy",
     "ollama",
@@ -133,6 +134,7 @@ codex-keyring-store = { path = "keyring-store" }
 codex-linux-sandbox = { path = "linux-sandbox" }
 codex-lmstudio = { path = "lmstudio" }
 codex-login = { path = "login" }
+codex-mcp = { path = "codex-mcp" }
 codex-mcp-server = { path = "mcp-server" }
 codex-network-proxy = { path = "network-proxy" }
 codex-ollama = { path = "ollama" }

codex-rs/app-server/src/codex_message_processor.rs

@@ -5039,9 +5039,12 @@ impl CodexMessageProcessor {
                 return;
             }
         };
+        let mcp_config = config.to_mcp_config(self.thread_manager.plugins_manager().as_ref());
+        let auth = self.auth_manager.auth().await;
 
         tokio::spawn(async move {
-            Self::list_mcp_server_status_task(outgoing, request, params, config).await;
+            Self::list_mcp_server_status_task(outgoing, request, params, config, mcp_config, auth)
+                .await;
         });
     }
 
@@ -5050,8 +5053,15 @@ impl CodexMessageProcessor {
         request_id: ConnectionRequestId,
         params: ListMcpServerStatusParams,
         config: Config,
+        mcp_config: codex_core::mcp::McpConfig,
+        auth: Option<CodexAuth>,
     ) {
-        let snapshot = collect_mcp_snapshot(&config).await;
+        let snapshot = collect_mcp_snapshot(
+            &mcp_config,
+            auth.as_ref(),
+            request_id.request_id.to_string(),
+        )
+        .await;
 
         let tools_by_server = group_tools_by_server(&snapshot.tools);
 

codex-rs/codex-mcp/BUILD.bazel

@@ -0,0 +1,6 @@
+load("//:defs.bzl", "codex_rust_crate")
+
+codex_rust_crate(
+    name = "codex-mcp",
+    crate_name = "codex_mcp",
+)

codex-rs/codex-mcp/Cargo.toml

@@ -0,0 +1,40 @@
+[package]
+edition.workspace = true
+license.workspace = true
+name = "codex-mcp"
+version.workspace = true
+
+[lib]
+name = "codex_mcp"
+path = "src/lib.rs"
+
+[lints]
+workspace = true
+
+[dependencies]
+anyhow = { workspace = true }
+async-channel = { workspace = true }
+codex-async-utils = { workspace = true }
+codex-config = { workspace = true }
+codex-login = { workspace = true }
+codex-otel = { workspace = true }
+codex-plugin = { workspace = true }
+codex-protocol = { workspace = true }
+codex-rmcp-client = { workspace = true }
+codex-utils-plugins = { workspace = true }
+futures = { workspace = true }
+regex-lite = { workspace = true }
+rmcp = { workspace = true, default-features = false, features = ["base64", "macros", "schemars", "server"] }
+serde = { workspace = true, features = ["derive"] }
+serde_json = { workspace = true }
+sha1 = { workspace = true }
+thiserror = { workspace = true }
+tokio = { workspace = true, features = ["macros", "rt-multi-thread"] }
+tokio-util = { workspace = true, features = ["rt"] }
+tracing = { workspace = true }
+url = { workspace = true }
+
+[dev-dependencies]
+pretty_assertions = { workspace = true }
+rmcp = { workspace = true, default-features = false, features = ["base64", "macros", "schemars", "server"] }
+tempfile = { workspace = true }

codex-rs/codex-mcp/src/lib.rs

@@ -0,0 +1,2 @@
+pub mod mcp;
+pub mod mcp_connection_manager;

codex-rs/codex-mcp/src/mcp/auth.rs

@@ -9,8 +9,8 @@ use codex_rmcp_client::discover_streamable_http_oauth;
 use futures::future::join_all;
 use tracing::warn;
 
-use crate::config::types::McpServerConfig;
-use crate::config::types::McpServerTransportConfig;
+use codex_config::McpServerConfig;
+use codex_config::McpServerTransportConfig;
 
 #[derive(Debug, Clone)]
 pub struct McpOAuthLoginConfig {

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

@@ -1,36 +1,37 @@
 pub mod auth;
 mod skill_dependencies;
-pub(crate) use skill_dependencies::maybe_prompt_and_install_mcp_dependencies;
+pub use skill_dependencies::canonical_mcp_server_key;
+pub use skill_dependencies::collect_missing_mcp_dependencies;
 
 use std::collections::HashMap;
 use std::env;
 use std::path::PathBuf;
-use std::sync::Arc;
 use std::time::Duration;
 
 use async_channel::unbounded;
+use codex_config::Constrained;
+use codex_config::McpServerConfig;
+use codex_config::McpServerTransportConfig;
+use codex_login::CodexAuth;
+use codex_plugin::PluginCapabilitySummary;
 use codex_protocol::mcp::Resource;
 use codex_protocol::mcp::ResourceTemplate;
 use codex_protocol::mcp::Tool;
+use codex_protocol::protocol::AskForApproval;
 use codex_protocol::protocol::McpListToolsResponseEvent;
 use codex_protocol::protocol::SandboxPolicy;
+use codex_rmcp_client::OAuthCredentialsStoreMode;
 use serde_json::Value;
 
-use crate::AuthManager;
-use crate::CodexAuth;
-use crate::config::Config;
-use crate::config::types::McpServerConfig;
-use crate::config::types::McpServerTransportConfig;
 use crate::mcp::auth::compute_auth_statuses;
 use crate::mcp_connection_manager::McpConnectionManager;
 use crate::mcp_connection_manager::SandboxState;
 use crate::mcp_connection_manager::codex_apps_tools_cache_key;
-use crate::plugins::PluginCapabilitySummary;
-use crate::plugins::PluginsManager;
+pub type McpManager = McpConnectionManager;
 
 const MCP_TOOL_NAME_PREFIX: &str = "mcp";
 const MCP_TOOL_NAME_DELIMITER: &str = "__";
-pub(crate) const CODEX_APPS_MCP_SERVER_NAME: &str = "codex_apps";
+pub const CODEX_APPS_MCP_SERVER_NAME: &str = "codex_apps";
 const CODEX_CONNECTORS_TOKEN_ENV_VAR: &str = "CODEX_CONNECTORS_TOKEN";
 
 /// The Responses API requires tool names to match `^[a-zA-Z0-9_-]+$`.
@@ -59,6 +60,46 @@ pub fn qualified_mcp_tool_name_prefix(server_name: &str) -> String {
     ))
 }
 
+/// MCP runtime settings derived from `codex_core::config::Config`.
+///
+/// This struct should contain only long-lived configuration values that the
+/// `codex-mcp` crate needs to construct server transports, enforce MCP
+/// approval/sandbox policy, locate OAuth state, and merge plugin-provided MCP
+/// servers. Request-scoped or auth-scoped state should not be stored here;
+/// thread those values explicitly into runtime entry points such as
+/// [`with_codex_apps_mcp`] and [`collect_mcp_snapshot`] so config objects do
+/// not go stale when auth changes.
+#[derive(Debug, Clone)]
+pub struct McpConfig {
+    /// Base URL for ChatGPT-hosted app MCP servers, copied from the root config.
+    pub chatgpt_base_url: String,
+    /// Codex home directory used for MCP OAuth state and app-tool cache files.
+    pub codex_home: PathBuf,
+    /// Preferred credential store for MCP OAuth tokens.
+    pub mcp_oauth_credentials_store_mode: OAuthCredentialsStoreMode,
+    /// Optional fixed localhost callback port for MCP OAuth login.
+    pub mcp_oauth_callback_port: Option<u16>,
+    /// Optional OAuth redirect URI override for MCP login.
+    pub mcp_oauth_callback_url: Option<String>,
+    /// Whether skill MCP dependency installation prompts are enabled.
+    pub skill_mcp_dependency_install_enabled: bool,
+    /// Approval policy used for MCP tool calls and MCP elicitation requests.
+    pub approval_policy: Constrained<AskForApproval>,
+    /// Optional path to `codex-linux-sandbox` for sandboxed MCP tool execution.
+    pub codex_linux_sandbox_exe: Option<PathBuf>,
+    /// Whether to use legacy Landlock behavior in the MCP sandbox state.
+    pub use_legacy_landlock: bool,
+    /// Whether the app MCP integration is enabled by config.
+    ///
+    /// ChatGPT auth is checked separately at runtime before the built-in apps
+    /// MCP server is added.
+    pub apps_enabled: bool,
+    /// User-configured and plugin-provided MCP servers keyed by server name.
+    pub configured_mcp_servers: HashMap<String, McpServerConfig>,
+    /// Plugin metadata used to attribute MCP tools/connectors to plugin display names.
+    pub plugin_capability_summaries: Vec<PluginCapabilitySummary>,
+}
+
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct ToolPluginProvenance {
     plugin_display_names_by_connector_id: HashMap<String, Vec<String>>,
@@ -173,11 +214,11 @@ fn codex_apps_mcp_url_for_base_url(base_url: &str) -> String {
     }
 }
 
-pub(crate) fn codex_apps_mcp_url(config: &Config) -> String {
+pub(crate) fn codex_apps_mcp_url(config: &McpConfig) -> String {
     codex_apps_mcp_url_for_base_url(&config.chatgpt_base_url)
 }
 
-fn codex_apps_mcp_server_config(config: &Config, auth: Option<&CodexAuth>) -> McpServerConfig {
+fn codex_apps_mcp_server_config(config: &McpConfig, auth: Option<&CodexAuth>) -> McpServerConfig {
     let bearer_token_env_var = codex_apps_mcp_bearer_token_env_var();
     let http_headers = if bearer_token_env_var.is_some() {
         None
@@ -206,13 +247,12 @@ fn codex_apps_mcp_server_config(config: &Config, auth: Option<&CodexAuth>) -> Mc
     }
 }
 
-pub(crate) fn with_codex_apps_mcp(
+pub fn with_codex_apps_mcp(
     mut servers: HashMap<String, McpServerConfig>,
-    connectors_enabled: bool,
     auth: Option<&CodexAuth>,
-    config: &Config,
+    config: &McpConfig,
 ) -> HashMap<String, McpServerConfig> {
-    if connectors_enabled {
+    if config.apps_enabled && auth.is_some_and(CodexAuth::is_chatgpt_auth) {
         servers.insert(
             CODEX_APPS_MCP_SERVER_NAME.to_string(),
             codex_apps_mcp_server_config(config, auth),
@@ -223,69 +263,29 @@ pub(crate) fn with_codex_apps_mcp(
     servers
 }
 
-pub struct McpManager {
-    plugins_manager: Arc<PluginsManager>,
+pub fn configured_mcp_servers(config: &McpConfig) -> HashMap<String, McpServerConfig> {
+    config.configured_mcp_servers.clone()
 }
 
-impl McpManager {
-    pub fn new(plugins_manager: Arc<PluginsManager>) -> Self {
-        Self { plugins_manager }
-    }
-
-    pub fn configured_servers(&self, config: &Config) -> HashMap<String, McpServerConfig> {
-        configured_mcp_servers(config, self.plugins_manager.as_ref())
-    }
-
-    pub fn effective_servers(
-        &self,
-        config: &Config,
-        auth: Option<&CodexAuth>,
-    ) -> HashMap<String, McpServerConfig> {
-        effective_mcp_servers(config, auth, self.plugins_manager.as_ref())
-    }
-
-    pub fn tool_plugin_provenance(&self, config: &Config) -> ToolPluginProvenance {
-        let loaded_plugins = self.plugins_manager.plugins_for_config(config);
-        ToolPluginProvenance::from_capability_summaries(loaded_plugins.capability_summaries())
-    }
-}
-
-fn configured_mcp_servers(
-    config: &Config,
-    plugins_manager: &PluginsManager,
-) -> HashMap<String, McpServerConfig> {
-    let loaded_plugins = plugins_manager.plugins_for_config(config);
-    let mut servers = config.mcp_servers.get().clone();
-    for (name, plugin_server) in loaded_plugins.effective_mcp_servers() {
-        servers.entry(name).or_insert(plugin_server);
-    }
-    servers
-}
-
-fn effective_mcp_servers(
-    config: &Config,
+pub fn effective_mcp_servers(
+    config: &McpConfig,
     auth: Option<&CodexAuth>,
-    plugins_manager: &PluginsManager,
 ) -> HashMap<String, McpServerConfig> {
-    let servers = configured_mcp_servers(config, plugins_manager);
-    with_codex_apps_mcp(
-        servers,
-        config.features.apps_enabled_for_auth(auth),
-        auth,
-        config,
-    )
+    let servers = configured_mcp_servers(config);
+    with_codex_apps_mcp(servers, auth, config)
 }
 
-pub async fn collect_mcp_snapshot(config: &Config) -> McpListToolsResponseEvent {
-    let auth_manager = AuthManager::shared(
-        config.codex_home.clone(),
-        /*enable_codex_api_key_env*/ false,
-        config.cli_auth_credentials_store_mode,
-    );
-    let auth = auth_manager.auth().await;
-    let mcp_manager = McpManager::new(Arc::new(PluginsManager::new(config.codex_home.clone())));
-    let mcp_servers = mcp_manager.effective_servers(config, auth.as_ref());
-    let tool_plugin_provenance = mcp_manager.tool_plugin_provenance(config);
+pub fn tool_plugin_provenance(config: &McpConfig) -> ToolPluginProvenance {
+    ToolPluginProvenance::from_capability_summaries(&config.plugin_capability_summaries)
+}
+
+pub async fn collect_mcp_snapshot(
+    config: &McpConfig,
+    auth: Option<&CodexAuth>,
+    submit_id: String,
+) -> McpListToolsResponseEvent {
+    let mcp_servers = effective_mcp_servers(config, auth);
+    let tool_plugin_provenance = tool_plugin_provenance(config);
     if mcp_servers.is_empty() {
         return McpListToolsResponseEvent {
             tools: HashMap::new(),
@@ -306,18 +306,19 @@ pub async fn collect_mcp_snapshot(config: &Config) -> McpListToolsResponseEvent
         sandbox_policy: SandboxPolicy::new_read_only_policy(),
         codex_linux_sandbox_exe: config.codex_linux_sandbox_exe.clone(),
         sandbox_cwd: env::current_dir().unwrap_or_else(|_| PathBuf::from("/")),
-        use_legacy_landlock: config.features.use_legacy_landlock(),
+        use_legacy_landlock: config.use_legacy_landlock,
     };
 
     let (mcp_connection_manager, cancel_token) = McpConnectionManager::new(
         &mcp_servers,
         config.mcp_oauth_credentials_store_mode,
         auth_status_entries.clone(),
-        &config.permissions.approval_policy,
+        &config.approval_policy,
+        submit_id,
         tx_event,
         sandbox_state,
         config.codex_home.clone(),
-        codex_apps_tools_cache_key(auth.as_ref()),
+        codex_apps_tools_cache_key(auth),
         tool_plugin_provenance,
     )
     .await;
@@ -359,7 +360,7 @@ pub fn group_tools_by_server(
     grouped
 }
 
-pub(crate) async fn collect_mcp_snapshot_from_manager(
+pub async fn collect_mcp_snapshot_from_manager(
     mcp_connection_manager: &McpConnectionManager,
     auth_status_entries: HashMap<String, crate::mcp::auth::McpAuthStatusEntry>,
 ) -> McpListToolsResponseEvent {
@@ -372,7 +373,7 @@ pub(crate) async fn collect_mcp_snapshot_from_manager(
     let auth_statuses = auth_status_entries
         .iter()
         .map(|(name, entry)| (name.clone(), entry.auth_status))
-        .collect();
+        .collect::<HashMap<_, _>>();
 
     let tools = tools
         .into_iter()
@@ -389,7 +390,7 @@ pub(crate) async fn collect_mcp_snapshot_from_manager(
                 None
             }
         })
-        .collect();
+        .collect::<HashMap<_, _>>();
 
     let resources = resources
         .into_iter()
@@ -424,7 +425,7 @@ pub(crate) async fn collect_mcp_snapshot_from_manager(
                 .collect::<Vec<_>>();
             (name, resources)
         })
-        .collect();
+        .collect::<HashMap<_, _>>();
 
     let resource_templates = resource_templates
         .into_iter()
@@ -460,7 +461,7 @@ pub(crate) async fn collect_mcp_snapshot_from_manager(
                 .collect::<Vec<_>>();
             (name, templates)
         })
-        .collect();
+        .collect::<HashMap<_, _>>();
 
     McpListToolsResponseEvent {
         tools,

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

@@ -1,34 +1,28 @@
 use super::*;
-use crate::config::CONFIG_TOML_FILE;
-use crate::config::ConfigBuilder;
-use crate::plugins::AppConnectorId;
-use crate::plugins::PluginCapabilitySummary;
-use codex_features::Feature;
+use codex_config::Constrained;
+use codex_login::CodexAuth;
+use codex_plugin::AppConnectorId;
+use codex_plugin::PluginCapabilitySummary;
+use codex_protocol::protocol::AskForApproval;
 use pretty_assertions::assert_eq;
-use std::fs;
-use std::path::Path;
-use toml::Value;
+use std::collections::HashMap;
+use std::path::PathBuf;
 
-fn write_file(path: &Path, contents: &str) {
-    fs::create_dir_all(path.parent().expect("file should have a parent")).unwrap();
-    fs::write(path, contents).unwrap();
-}
-
-fn plugin_config_toml() -> String {
-    let mut root = toml::map::Map::new();
-
-    let mut features = toml::map::Map::new();
-    features.insert("plugins".to_string(), Value::Boolean(true));
-    root.insert("features".to_string(), Value::Table(features));
-
-    let mut plugin = toml::map::Map::new();
-    plugin.insert("enabled".to_string(), Value::Boolean(true));
-
-    let mut plugins = toml::map::Map::new();
-    plugins.insert("sample@test".to_string(), Value::Table(plugin));
-    root.insert("plugins".to_string(), Value::Table(plugins));
-
-    toml::to_string(&Value::Table(root)).expect("plugin test config should serialize")
+fn test_mcp_config(codex_home: PathBuf) -> McpConfig {
+    McpConfig {
+        chatgpt_base_url: "https://chatgpt.com".to_string(),
+        codex_home,
+        mcp_oauth_credentials_store_mode: OAuthCredentialsStoreMode::default(),
+        mcp_oauth_callback_port: None,
+        mcp_oauth_callback_url: None,
+        skill_mcp_dependency_install_enabled: true,
+        approval_policy: Constrained::allow_any(AskForApproval::OnFailure),
+        codex_linux_sandbox_exe: None,
+        use_legacy_landlock: false,
+        apps_enabled: false,
+        configured_mcp_servers: HashMap::new(),
+        plugin_capability_summaries: Vec::new(),
+    }
 }
 
 fn make_tool(name: &str) -> Tool {
@@ -153,8 +147,7 @@ fn codex_apps_mcp_url_for_base_url_keeps_existing_paths() {
 
 #[test]
 fn codex_apps_mcp_url_uses_legacy_codex_apps_path() {
-    let mut config = crate::config::test_config();
-    config.chatgpt_base_url = "https://chatgpt.com".to_string();
+    let config = test_mcp_config(PathBuf::from("/tmp"));
 
     assert_eq!(
         codex_apps_mcp_url(&config),
@@ -164,25 +157,15 @@ fn codex_apps_mcp_url_uses_legacy_codex_apps_path() {
 
 #[test]
 fn codex_apps_server_config_uses_legacy_codex_apps_path() {
-    let mut config = crate::config::test_config();
-    config.chatgpt_base_url = "https://chatgpt.com".to_string();
+    let mut config = test_mcp_config(PathBuf::from("/tmp"));
+    let auth = CodexAuth::create_dummy_chatgpt_auth_for_testing();
 
-    let mut servers = with_codex_apps_mcp(
-        HashMap::new(),
-        /*connectors_enabled*/ false,
-        /*auth*/ None,
-        &config,
-    );
+    let mut servers = with_codex_apps_mcp(HashMap::new(), /*auth*/ None, &config);
     assert!(!servers.contains_key(CODEX_APPS_MCP_SERVER_NAME));
 
-    config
-        .features
-        .enable(Feature::Apps)
-        .expect("test config should allow apps");
+    config.apps_enabled = true;
 
-    servers = with_codex_apps_mcp(
-        servers, /*connectors_enabled*/ true, /*auth*/ None, &config,
-    );
+    servers = with_codex_apps_mcp(servers, Some(&auth), &config);
     let server = servers
         .get(CODEX_APPS_MCP_SERVER_NAME)
         .expect("codex apps should be present when apps is enabled");
@@ -195,44 +178,13 @@ fn codex_apps_server_config_uses_legacy_codex_apps_path() {
 }
 
 #[tokio::test]
-async fn effective_mcp_servers_include_plugins_without_overriding_user_config() {
+async fn effective_mcp_servers_preserve_user_servers_and_add_codex_apps() {
     let codex_home = tempfile::tempdir().expect("tempdir");
-    let plugin_root = codex_home
-        .path()
-        .join("plugins/cache")
-        .join("test/sample/local");
-    write_file(
-        &plugin_root.join(".codex-plugin/plugin.json"),
-        r#"{"name":"sample"}"#,
-    );
-    write_file(
-        &plugin_root.join(".mcp.json"),
-        r#"{
-  "mcpServers": {
-    "sample": {
-      "type": "http",
-      "url": "https://plugin.example/mcp"
-    },
-    "docs": {
-      "type": "http",
-      "url": "https://docs.example/mcp"
-    }
-  }
-}"#,
-    );
-    write_file(
-        &codex_home.path().join(CONFIG_TOML_FILE),
-        &plugin_config_toml(),
-    );
+    let mut config = test_mcp_config(codex_home.path().to_path_buf());
+    config.apps_enabled = true;
+    let auth = CodexAuth::create_dummy_chatgpt_auth_for_testing();
 
-    let mut config = ConfigBuilder::default()
-        .codex_home(codex_home.path().to_path_buf())
-        .build()
-        .await
-        .expect("config should load");
-
-    let mut configured_servers = config.mcp_servers.get().clone();
-    configured_servers.insert(
+    config.configured_mcp_servers.insert(
         "sample".to_string(),
         McpServerConfig {
             transport: McpServerTransportConfig::StreamableHttp {
@@ -253,16 +205,37 @@ async fn effective_mcp_servers_include_plugins_without_overriding_user_config()
             tools: HashMap::new(),
         },
     );
-    config
-        .mcp_servers
-        .set(configured_servers)
-        .expect("test config should accept MCP servers");
+    config.configured_mcp_servers.insert(
+        "docs".to_string(),
+        McpServerConfig {
+            transport: McpServerTransportConfig::StreamableHttp {
+                url: "https://docs.example/mcp".to_string(),
+                bearer_token_env_var: None,
+                http_headers: None,
+                env_http_headers: None,
+            },
+            enabled: true,
+            required: false,
+            disabled_reason: None,
+            startup_timeout_sec: None,
+            tool_timeout_sec: None,
+            enabled_tools: None,
+            disabled_tools: None,
+            scopes: None,
+            oauth_resource: None,
+            tools: HashMap::new(),
+        },
+    );
 
-    let mcp_manager = McpManager::new(Arc::new(PluginsManager::new(config.codex_home.clone())));
-    let effective = mcp_manager.effective_servers(&config, /*auth*/ None);
+    let effective = effective_mcp_servers(&config, Some(&auth));
 
     let sample = effective.get("sample").expect("user server should exist");
-    let docs = effective.get("docs").expect("plugin server should exist");
+    let docs = effective
+        .get("docs")
+        .expect("configured server should exist");
+    let codex_apps = effective
+        .get(CODEX_APPS_MCP_SERVER_NAME)
+        .expect("codex apps server should exist");
 
     match &sample.transport {
         McpServerTransportConfig::StreamableHttp { url, .. } => {
@@ -276,4 +249,10 @@ async fn effective_mcp_servers_include_plugins_without_overriding_user_config()
         }
         other => panic!("expected streamable http transport, got {other:?}"),
     }
+    match &codex_apps.transport {
+        McpServerTransportConfig::StreamableHttp { url, .. } => {
+            assert_eq!(url, "https://chatgpt.com/backend-api/wham/apps");
+        }
+        other => panic!("expected streamable http transport, got {other:?}"),
+    }
 }

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

@@ -0,0 +1,166 @@
+use std::collections::HashMap;
+use std::collections::HashSet;
+
+use codex_config::McpServerConfig;
+use codex_config::McpServerTransportConfig;
+use codex_protocol::protocol::SkillMetadata;
+use codex_protocol::protocol::SkillToolDependency;
+use tracing::warn;
+
+pub fn collect_missing_mcp_dependencies(
+    mentioned_skills: &[SkillMetadata],
+    installed: &HashMap<String, McpServerConfig>,
+) -> HashMap<String, McpServerConfig> {
+    let mut missing = HashMap::new();
+    let installed_keys: HashSet<String> = installed
+        .iter()
+        .map(|(name, config)| canonical_mcp_server_key(name, config))
+        .collect();
+    let mut seen_canonical_keys = HashSet::new();
+
+    for skill in mentioned_skills {
+        let Some(dependencies) = skill.dependencies.as_ref() else {
+            continue;
+        };
+
+        for tool in &dependencies.tools {
+            if !tool.r#type.eq_ignore_ascii_case("mcp") {
+                continue;
+            }
+            let dependency_key = match canonical_mcp_dependency_key(tool) {
+                Ok(key) => key,
+                Err(err) => {
+                    let dependency = tool.value.as_str();
+                    let skill_name = skill.name.as_str();
+                    warn!(
+                        "unable to auto-install MCP dependency {dependency} for skill {skill_name}: {err}",
+                    );
+                    continue;
+                }
+            };
+            if installed_keys.contains(&dependency_key)
+                || seen_canonical_keys.contains(&dependency_key)
+            {
+                continue;
+            }
+
+            let config = match mcp_dependency_to_server_config(tool) {
+                Ok(config) => config,
+                Err(err) => {
+                    let dependency = dependency_key.as_str();
+                    let skill_name = skill.name.as_str();
+                    warn!(
+                        "unable to auto-install MCP dependency {dependency} for skill {skill_name}: {err}",
+                    );
+                    continue;
+                }
+            };
+
+            missing.insert(tool.value.clone(), config);
+            seen_canonical_keys.insert(dependency_key);
+        }
+    }
+
+    missing
+}
+
+fn canonical_mcp_key(transport: &str, identifier: &str, fallback: &str) -> String {
+    let identifier = identifier.trim();
+    if identifier.is_empty() {
+        fallback.to_string()
+    } else {
+        format!("mcp__{transport}__{identifier}")
+    }
+}
+
+pub fn canonical_mcp_server_key(name: &str, config: &McpServerConfig) -> String {
+    match &config.transport {
+        McpServerTransportConfig::Stdio { command, .. } => {
+            canonical_mcp_key("stdio", command, name)
+        }
+        McpServerTransportConfig::StreamableHttp { url, .. } => {
+            canonical_mcp_key("streamable_http", url, name)
+        }
+    }
+}
+
+fn canonical_mcp_dependency_key(dependency: &SkillToolDependency) -> Result<String, String> {
+    let transport = dependency.transport.as_deref().unwrap_or("streamable_http");
+    if transport.eq_ignore_ascii_case("streamable_http") {
+        let url = dependency
+            .url
+            .as_ref()
+            .ok_or_else(|| "missing url for streamable_http dependency".to_string())?;
+        return Ok(canonical_mcp_key("streamable_http", url, &dependency.value));
+    }
+    if transport.eq_ignore_ascii_case("stdio") {
+        let command = dependency
+            .command
+            .as_ref()
+            .ok_or_else(|| "missing command for stdio dependency".to_string())?;
+        return Ok(canonical_mcp_key("stdio", command, &dependency.value));
+    }
+    Err(format!("unsupported transport {transport}"))
+}
+
+fn mcp_dependency_to_server_config(
+    dependency: &SkillToolDependency,
+) -> Result<McpServerConfig, String> {
+    let transport = dependency.transport.as_deref().unwrap_or("streamable_http");
+    if transport.eq_ignore_ascii_case("streamable_http") {
+        let url = dependency
+            .url
+            .as_ref()
+            .ok_or_else(|| "missing url for streamable_http dependency".to_string())?;
+        return Ok(McpServerConfig {
+            transport: McpServerTransportConfig::StreamableHttp {
+                url: url.clone(),
+                bearer_token_env_var: None,
+                http_headers: None,
+                env_http_headers: None,
+            },
+            enabled: true,
+            required: false,
+            disabled_reason: None,
+            startup_timeout_sec: None,
+            tool_timeout_sec: None,
+            enabled_tools: None,
+            disabled_tools: None,
+            scopes: None,
+            oauth_resource: None,
+            tools: HashMap::new(),
+        });
+    }
+
+    if transport.eq_ignore_ascii_case("stdio") {
+        let command = dependency
+            .command
+            .as_ref()
+            .ok_or_else(|| "missing command for stdio dependency".to_string())?;
+        return Ok(McpServerConfig {
+            transport: McpServerTransportConfig::Stdio {
+                command: command.clone(),
+                args: Vec::new(),
+                env: None,
+                env_vars: Vec::new(),
+                cwd: None,
+            },
+            enabled: true,
+            required: false,
+            disabled_reason: None,
+            startup_timeout_sec: None,
+            tool_timeout_sec: None,
+            enabled_tools: None,
+            disabled_tools: None,
+            scopes: None,
+            oauth_resource: None,
+            tools: HashMap::new(),
+        });
+    }
+
+    Err(format!("unsupported transport {transport}"))
+}
+
+#[cfg(test)]
+#[path = "skill_dependencies_tests.rs"]
+mod tests;

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

@@ -1,5 +1,6 @@
 use super::*;
-use crate::model::SkillDependencies;
+use codex_protocol::protocol::SkillDependencies;
+use codex_protocol::protocol::SkillMetadata;
 use codex_protocol::protocol::SkillScope;
 use pretty_assertions::assert_eq;
 use std::path::PathBuf;
@@ -11,9 +12,9 @@ fn skill_with_tools(tools: Vec<SkillToolDependency>) -> SkillMetadata {
         short_description: None,
         interface: None,
         dependencies: Some(SkillDependencies { tools }),
-        policy: None,
-        path_to_skills_md: PathBuf::from("skill"),
+        path: PathBuf::from("skill"),
         scope: SkillScope::User,
+        enabled: true,
     }
 }
 

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

@@ -20,9 +20,13 @@ use std::time::Duration;
 use std::time::Instant;
 
 use crate::mcp::CODEX_APPS_MCP_SERVER_NAME;
+use crate::mcp::McpConfig;
 use crate::mcp::ToolPluginProvenance;
 use crate::mcp::auth::McpAuthStatusEntry;
+use crate::mcp::configured_mcp_servers;
+use crate::mcp::effective_mcp_servers;
 use crate::mcp::sanitize_responses_api_tool_name;
+use crate::mcp::tool_plugin_provenance;
 use anyhow::Context;
 use anyhow::Result;
 use anyhow::anyhow;
@@ -79,11 +83,11 @@ use tracing::instrument;
 use tracing::warn;
 use url::Url;
 
-use crate::codex::INITIAL_SUBMIT_ID;
-use crate::config::types::McpServerConfig;
-use crate::config::types::McpServerTransportConfig;
-use crate::connectors::is_connector_id_allowed;
-use crate::connectors::sanitize_name;
+use codex_config::McpServerConfig;
+use codex_config::McpServerTransportConfig;
+use codex_login::CodexAuth;
+use codex_utils_plugins::mcp_connector::is_connector_id_allowed;
+use codex_utils_plugins::mcp_connector::sanitize_name;
 
 /// Delimiter used to separate the server name from the tool name in a fully
 /// qualified tool name.
@@ -112,9 +116,7 @@ fn sha1_hex(s: &str) -> String {
     format!("{sha1:x}")
 }
 
-pub(crate) fn codex_apps_tools_cache_key(
-    auth: Option<&crate::CodexAuth>,
-) -> CodexAppsToolsCacheKey {
+pub fn codex_apps_tools_cache_key(auth: Option<&CodexAuth>) -> CodexAppsToolsCacheKey {
     let token_data = auth.and_then(|auth| auth.get_token_data().ok());
     let account_id = token_data
         .as_ref()
@@ -180,20 +182,20 @@ where
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
-pub(crate) struct ToolInfo {
-    pub(crate) server_name: String,
-    pub(crate) tool_name: String,
-    pub(crate) tool_namespace: String,
-    pub(crate) tool: Tool,
-    pub(crate) connector_id: Option<String>,
-    pub(crate) connector_name: Option<String>,
+pub struct ToolInfo {
+    pub server_name: String,
+    pub tool_name: String,
+    pub tool_namespace: String,
+    pub tool: Tool,
+    pub connector_id: Option<String>,
+    pub connector_name: Option<String>,
     #[serde(default)]
-    pub(crate) plugin_display_names: Vec<String>,
-    pub(crate) connector_description: Option<String>,
+    pub plugin_display_names: Vec<String>,
+    pub connector_description: Option<String>,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-pub(crate) struct CodexAppsToolsCacheKey {
+pub struct CodexAppsToolsCacheKey {
     account_id: Option<String>,
     chatgpt_user_id: Option<String>,
     is_workspace_account: bool,
@@ -576,14 +578,30 @@ pub struct SandboxState {
 }
 
 /// A thin wrapper around a set of running [`RmcpClient`] instances.
-pub(crate) struct McpConnectionManager {
+pub struct McpConnectionManager {
     clients: HashMap<String, AsyncManagedClient>,
     server_origins: HashMap<String, String>,
     elicitation_requests: ElicitationRequestManager,
 }
 
 impl McpConnectionManager {
-    pub(crate) fn new_uninitialized(approval_policy: &Constrained<AskForApproval>) -> Self {
+    pub fn configured_servers(&self, config: &McpConfig) -> HashMap<String, McpServerConfig> {
+        configured_mcp_servers(config)
+    }
+
+    pub fn effective_servers(
+        &self,
+        config: &McpConfig,
+        auth: Option<&CodexAuth>,
+    ) -> HashMap<String, McpServerConfig> {
+        effective_mcp_servers(config, auth)
+    }
+
+    pub fn tool_plugin_provenance(&self, config: &McpConfig) -> ToolPluginProvenance {
+        tool_plugin_provenance(config)
+    }
+
+    pub fn new_uninitialized(approval_policy: &Constrained<AskForApproval>) -> Self {
         Self {
             clients: HashMap::new(),
             server_origins: HashMap::new(),
@@ -591,18 +609,11 @@ impl McpConnectionManager {
         }
     }
 
-    #[cfg(test)]
-    pub(crate) fn new_mcp_connection_manager_for_tests(
-        approval_policy: &Constrained<AskForApproval>,
-    ) -> Self {
-        Self::new_uninitialized(approval_policy)
-    }
-
-    pub(crate) fn has_servers(&self) -> bool {
+    pub fn has_servers(&self) -> bool {
         !self.clients.is_empty()
     }
 
-    pub(crate) fn server_origin(&self, server_name: &str) -> Option<&str> {
+    pub fn server_origin(&self, server_name: &str) -> Option<&str> {
         self.server_origins.get(server_name).map(String::as_str)
     }
 
@@ -618,6 +629,7 @@ impl McpConnectionManager {
         store_mode: OAuthCredentialsStoreMode,
         auth_entries: HashMap<String, McpAuthStatusEntry>,
         approval_policy: &Constrained<AskForApproval>,
+        submit_id: String,
         tx_event: Sender<Event>,
         initial_sandbox_state: SandboxState,
         codex_home: PathBuf,
@@ -630,6 +642,7 @@ impl McpConnectionManager {
         let mut join_set = JoinSet::new();
         let elicitation_requests = ElicitationRequestManager::new(approval_policy.value());
         let tool_plugin_provenance = Arc::new(tool_plugin_provenance);
+        let startup_submit_id = submit_id.clone();
         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) {
@@ -637,6 +650,7 @@ impl McpConnectionManager {
             }
             let cancel_token = cancel_token.child_token();
             let _ = emit_update(
+                startup_submit_id.as_str(),
                 &tx_event,
                 McpStartupUpdateEvent {
                     server: server_name.clone(),
@@ -664,6 +678,7 @@ impl McpConnectionManager {
             );
             clients.insert(server_name.clone(), async_managed_client.clone());
             let tx_event = tx_event.clone();
+            let submit_id = startup_submit_id.clone();
             let auth_entry = auth_entries.get(&server_name).cloned();
             let sandbox_state = initial_sandbox_state.clone();
             join_set.spawn(async move {
@@ -695,6 +710,7 @@ impl McpConnectionManager {
                 };
 
                 let _ = emit_update(
+                    submit_id.as_str(),
                     &tx_event,
                     McpStartupUpdateEvent {
                         server: server_name.clone(),
@@ -728,7 +744,7 @@ impl McpConnectionManager {
             }
             let _ = tx_event
                 .send(Event {
-                    id: INITIAL_SUBMIT_ID.to_owned(),
+                    id: startup_submit_id,
                     msg: EventMsg::McpStartupComplete(summary),
                 })
                 .await;
@@ -756,7 +772,7 @@ impl McpConnectionManager {
             .await
     }
 
-    pub(crate) async fn wait_for_server_ready(&self, server_name: &str, timeout: Duration) -> bool {
+    pub async fn wait_for_server_ready(&self, server_name: &str, timeout: Duration) -> bool {
         let Some(async_managed_client) = self.clients.get(server_name) else {
             return false;
         };
@@ -767,7 +783,7 @@ impl McpConnectionManager {
         }
     }
 
-    pub(crate) async fn required_startup_failures(
+    pub async fn required_startup_failures(
         &self,
         required_servers: &[String],
     ) -> Vec<McpStartupFailure> {
@@ -1113,12 +1129,13 @@ impl McpConnectionManager {
 }
 
 async fn emit_update(
+    submit_id: &str,
     tx_event: &Sender<Event>,
     update: McpStartupUpdateEvent,
 ) -> Result<(), async_channel::SendError<Event>> {
     tx_event
         .send(Event {
-            id: INITIAL_SUBMIT_ID.to_owned(),
+            id: submit_id.to_string(),
             msg: EventMsg::McpStartupUpdate(update),
         })
         .await
@@ -1166,7 +1183,7 @@ fn filter_tools(tools: Vec<ToolInfo>, filter: &ToolFilter) -> Vec<ToolInfo> {
         .collect()
 }
 
-pub(crate) fn filter_non_codex_apps_mcp_tools_only(
+pub fn filter_non_codex_apps_mcp_tools_only(
     mcp_tools: &HashMap<String, ToolInfo>,
 ) -> HashMap<String, ToolInfo> {
     mcp_tools

codex-rs/config/src/lib.rs

@@ -3,6 +3,8 @@ mod config_requirements;
 mod constraint;
 mod diagnostics;
 mod fingerprint;
+mod mcp_edit;
+mod mcp_types;
 mod merge;
 mod overrides;
 mod project_root_markers;
@@ -50,6 +52,14 @@ pub use diagnostics::format_config_error;
 pub use diagnostics::format_config_error_with_source;
 pub use diagnostics::io_error_from_config_error;
 pub use fingerprint::version_for_toml;
+pub use mcp_edit::ConfigEditsBuilder;
+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::McpServerToolConfig;
+pub use mcp_types::McpServerTransportConfig;
+pub use mcp_types::RawMcpServerConfig;
 pub use merge::merge_toml_values;
 pub use overrides::build_cli_overrides_layer;
 pub use project_root_markers::default_project_root_markers;

codex-rs/config/src/mcp_edit.rs

@@ -0,0 +1,253 @@
+use std::collections::BTreeMap;
+use std::fs;
+use std::io::ErrorKind;
+use std::path::Path;
+use std::path::PathBuf;
+
+use tokio::task;
+use toml::Value as TomlValue;
+use toml_edit::DocumentMut;
+use toml_edit::Item as TomlItem;
+use toml_edit::Table as TomlTable;
+use toml_edit::value;
+
+use crate::AppToolApproval;
+use crate::CONFIG_TOML_FILE;
+use crate::McpServerConfig;
+use crate::McpServerTransportConfig;
+
+pub async fn load_global_mcp_servers(
+    codex_home: &Path,
+) -> std::io::Result<BTreeMap<String, McpServerConfig>> {
+    let config_path = codex_home.join(CONFIG_TOML_FILE);
+    let raw = match tokio::fs::read_to_string(&config_path).await {
+        Ok(raw) => raw,
+        Err(err) if err.kind() == ErrorKind::NotFound => return Ok(BTreeMap::new()),
+        Err(err) => return Err(err),
+    };
+    let parsed = toml::from_str::<TomlValue>(&raw)
+        .map_err(|err| std::io::Error::new(ErrorKind::InvalidData, err))?;
+    let Some(servers_value) = parsed.get("mcp_servers") else {
+        return Ok(BTreeMap::new());
+    };
+
+    ensure_no_inline_bearer_tokens(servers_value)?;
+
+    servers_value
+        .clone()
+        .try_into()
+        .map_err(|err| std::io::Error::new(ErrorKind::InvalidData, err))
+}
+
+fn ensure_no_inline_bearer_tokens(value: &TomlValue) -> std::io::Result<()> {
+    let Some(servers_table) = value.as_table() else {
+        return Ok(());
+    };
+
+    for (server_name, server_value) in servers_table {
+        if let Some(server_table) = server_value.as_table()
+            && server_table.contains_key("bearer_token")
+        {
+            let message = format!(
+                "mcp_servers.{server_name} uses unsupported `bearer_token`; set `bearer_token_env_var`."
+            );
+            return Err(std::io::Error::new(ErrorKind::InvalidData, message));
+        }
+    }
+
+    Ok(())
+}
+
+pub struct ConfigEditsBuilder {
+    codex_home: PathBuf,
+    mcp_servers: Option<BTreeMap<String, McpServerConfig>>,
+}
+
+impl ConfigEditsBuilder {
+    pub fn new(codex_home: &Path) -> Self {
+        Self {
+            codex_home: codex_home.to_path_buf(),
+            mcp_servers: None,
+        }
+    }
+
+    pub fn replace_mcp_servers(mut self, servers: &BTreeMap<String, McpServerConfig>) -> Self {
+        self.mcp_servers = Some(servers.clone());
+        self
+    }
+
+    pub async fn apply(self) -> std::io::Result<()> {
+        task::spawn_blocking(move || self.apply_blocking())
+            .await
+            .map_err(|err| {
+                std::io::Error::other(format!("config persistence task panicked: {err}"))
+            })?
+    }
+
+    fn apply_blocking(self) -> std::io::Result<()> {
+        let config_path = self.codex_home.join(CONFIG_TOML_FILE);
+        let mut doc = read_or_create_document(&config_path)?;
+        if let Some(servers) = self.mcp_servers.as_ref() {
+            replace_mcp_servers(&mut doc, servers);
+        }
+        fs::create_dir_all(&self.codex_home)?;
+        fs::write(config_path, doc.to_string())
+    }
+}
+
+fn read_or_create_document(config_path: &Path) -> std::io::Result<DocumentMut> {
+    match fs::read_to_string(config_path) {
+        Ok(raw) => raw
+            .parse::<DocumentMut>()
+            .map_err(|err| std::io::Error::new(ErrorKind::InvalidData, err)),
+        Err(err) if err.kind() == ErrorKind::NotFound => Ok(DocumentMut::new()),
+        Err(err) => Err(err),
+    }
+}
+
+fn replace_mcp_servers(doc: &mut DocumentMut, servers: &BTreeMap<String, McpServerConfig>) {
+    let root = doc.as_table_mut();
+    if servers.is_empty() {
+        root.remove("mcp_servers");
+        return;
+    }
+
+    let mut table = TomlTable::new();
+    table.set_implicit(true);
+    for (name, config) in servers {
+        table.insert(name, serialize_mcp_server(config));
+    }
+    root.insert("mcp_servers", TomlItem::Table(table));
+}
+
+fn serialize_mcp_server(config: &McpServerConfig) -> TomlItem {
+    let mut entry = TomlTable::new();
+    entry.set_implicit(false);
+
+    match &config.transport {
+        McpServerTransportConfig::Stdio {
+            command,
+            args,
+            env,
+            env_vars,
+            cwd,
+        } => {
+            entry["command"] = value(command.clone());
+            if !args.is_empty() {
+                entry["args"] = array_from_strings(args);
+            }
+            if let Some(env) = env
+                && !env.is_empty()
+            {
+                entry["env"] = table_from_pairs(env.iter());
+            }
+            if !env_vars.is_empty() {
+                entry["env_vars"] = array_from_strings(env_vars);
+            }
+            if let Some(cwd) = cwd {
+                entry["cwd"] = value(cwd.to_string_lossy().to_string());
+            }
+        }
+        McpServerTransportConfig::StreamableHttp {
+            url,
+            bearer_token_env_var,
+            http_headers,
+            env_http_headers,
+        } => {
+            entry["url"] = value(url.clone());
+            if let Some(env_var) = bearer_token_env_var {
+                entry["bearer_token_env_var"] = value(env_var.clone());
+            }
+            if let Some(headers) = http_headers
+                && !headers.is_empty()
+            {
+                entry["http_headers"] = table_from_pairs(headers.iter());
+            }
+            if let Some(headers) = env_http_headers
+                && !headers.is_empty()
+            {
+                entry["env_http_headers"] = table_from_pairs(headers.iter());
+            }
+        }
+    }
+
+    if !config.enabled {
+        entry["enabled"] = value(false);
+    }
+    if config.required {
+        entry["required"] = value(true);
+    }
+    if let Some(timeout) = config.startup_timeout_sec {
+        entry["startup_timeout_sec"] = value(timeout.as_secs_f64());
+    }
+    if let Some(timeout) = config.tool_timeout_sec {
+        entry["tool_timeout_sec"] = value(timeout.as_secs_f64());
+    }
+    if let Some(enabled_tools) = &config.enabled_tools
+        && !enabled_tools.is_empty()
+    {
+        entry["enabled_tools"] = array_from_strings(enabled_tools);
+    }
+    if let Some(disabled_tools) = &config.disabled_tools
+        && !disabled_tools.is_empty()
+    {
+        entry["disabled_tools"] = array_from_strings(disabled_tools);
+    }
+    if let Some(scopes) = &config.scopes
+        && !scopes.is_empty()
+    {
+        entry["scopes"] = array_from_strings(scopes);
+    }
+    if let Some(resource) = &config.oauth_resource
+        && !resource.is_empty()
+    {
+        entry["oauth_resource"] = value(resource.clone());
+    }
+    if !config.tools.is_empty() {
+        let mut tools = TomlTable::new();
+        tools.set_implicit(false);
+        let mut tool_entries: Vec<_> = config.tools.iter().collect();
+        tool_entries.sort_by(|(left, _), (right, _)| left.cmp(right));
+        for (name, tool_config) in tool_entries {
+            let mut tool_entry = TomlTable::new();
+            tool_entry.set_implicit(false);
+            if let Some(approval_mode) = tool_config.approval_mode {
+                tool_entry["approval_mode"] = value(match approval_mode {
+                    AppToolApproval::Auto => "auto",
+                    AppToolApproval::Prompt => "prompt",
+                    AppToolApproval::Approve => "approve",
+                });
+            }
+            tools.insert(name, TomlItem::Table(tool_entry));
+        }
+        entry.insert("tools", TomlItem::Table(tools));
+    }
+
+    TomlItem::Table(entry)
+}
+
+fn array_from_strings(values: &[String]) -> TomlItem {
+    let mut array = toml_edit::Array::new();
+    for value in values {
+        array.push(value.clone());
+    }
+    TomlItem::Value(array.into())
+}
+
+fn table_from_pairs<'a, I>(pairs: I) -> TomlItem
+where
+    I: IntoIterator<Item = (&'a String, &'a String)>,
+{
+    let mut entries: Vec<_> = pairs.into_iter().collect();
+    entries.sort_by(|(left, _), (right, _)| left.cmp(right));
+    let mut table = TomlTable::new();
+    table.set_implicit(false);
+    for (key, value_str) in entries {
+        table.insert(key, value(value_str.clone()));
+    }
+    TomlItem::Table(table)
+}
+
+#[cfg(test)]
+#[path = "mcp_edit_tests.rs"]
+mod tests;

codex-rs/config/src/mcp_edit_tests.rs

@@ -0,0 +1,79 @@
+use super::*;
+use crate::McpServerToolConfig;
+use pretty_assertions::assert_eq;
+use std::collections::HashMap;
+use std::time::SystemTime;
+use std::time::UNIX_EPOCH;
+
+#[tokio::test]
+async fn replace_mcp_servers_serializes_per_tool_approval_overrides() -> anyhow::Result<()> {
+    let unique_suffix = SystemTime::now().duration_since(UNIX_EPOCH)?.as_nanos();
+    let codex_home = std::env::temp_dir().join(format!(
+        "codex-config-mcp-edit-test-{}-{unique_suffix}",
+        std::process::id()
+    ));
+    let servers = BTreeMap::from([(
+        "docs".to_string(),
+        McpServerConfig {
+            transport: McpServerTransportConfig::Stdio {
+                command: "docs-server".to_string(),
+                args: Vec::new(),
+                env: None,
+                env_vars: Vec::new(),
+                cwd: None,
+            },
+            enabled: true,
+            required: false,
+            disabled_reason: None,
+            startup_timeout_sec: None,
+            tool_timeout_sec: None,
+            enabled_tools: None,
+            disabled_tools: None,
+            scopes: None,
+            oauth_resource: None,
+            tools: HashMap::from([
+                (
+                    "search".to_string(),
+                    McpServerToolConfig {
+                        approval_mode: Some(AppToolApproval::Approve),
+                    },
+                ),
+                (
+                    "read".to_string(),
+                    McpServerToolConfig {
+                        approval_mode: Some(AppToolApproval::Prompt),
+                    },
+                ),
+            ]),
+        },
+    )]);
+
+    ConfigEditsBuilder::new(&codex_home)
+        .replace_mcp_servers(&servers)
+        .apply()
+        .await?;
+
+    let config_path = codex_home.join(CONFIG_TOML_FILE);
+    let serialized = std::fs::read_to_string(&config_path)?;
+    assert_eq!(
+        serialized,
+        r#"[mcp_servers.docs]
+command = "docs-server"
+
+[mcp_servers.docs.tools]
+
+[mcp_servers.docs.tools.read]
+approval_mode = "prompt"
+
+[mcp_servers.docs.tools.search]
+approval_mode = "approve"
+"#
+    );
+
+    let loaded = load_global_mcp_servers(&codex_home).await?;
+    assert_eq!(loaded, servers);
+
+    std::fs::remove_dir_all(&codex_home)?;
+
+    Ok(())
+}

codex-rs/config/src/mcp_types.rs

@@ -0,0 +1,331 @@
+//! MCP server configuration types.
+
+use std::collections::HashMap;
+use std::fmt;
+use std::path::PathBuf;
+use std::time::Duration;
+
+use schemars::JsonSchema;
+use serde::Deserialize;
+use serde::Deserializer;
+use serde::Serialize;
+use serde::de::Error as SerdeError;
+
+use crate::RequirementSource;
+
+#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, Default, JsonSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum AppToolApproval {
+    #[default]
+    Auto,
+    Prompt,
+    Approve,
+}
+
+/// Human-readable reason a configured MCP server was disabled after requirements
+/// were applied.
+///
+/// `Display` is intentionally implemented for CLI/TUI status output; avoid
+/// relying on `Debug` because enum variant syntax is not part of the user-facing
+/// message contract.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum McpServerDisabledReason {
+    /// The server is disabled, but there is no more specific user-facing reason.
+    Unknown,
+    /// The server was disabled by config requirements from the given source.
+    Requirements { source: RequirementSource },
+}
+
+impl fmt::Display for McpServerDisabledReason {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            McpServerDisabledReason::Unknown => write!(f, "unknown"),
+            McpServerDisabledReason::Requirements { source } => {
+                write!(f, "requirements ({source})")
+            }
+        }
+    }
+}
+
+/// Per-tool approval settings for a single MCP server tool.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Default, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct McpServerToolConfig {
+    /// Approval mode for this tool.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub approval_mode: Option<AppToolApproval>,
+}
+
+#[derive(Serialize, Debug, Clone, PartialEq)]
+pub struct McpServerConfig {
+    #[serde(flatten)]
+    pub transport: McpServerTransportConfig,
+
+    /// When `false`, Codex skips initializing this MCP server.
+    #[serde(default = "default_enabled")]
+    pub enabled: bool,
+
+    /// When `true`, `codex exec` exits with an error if this MCP server fails to initialize.
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub required: bool,
+
+    /// Reason this server was disabled after applying requirements.
+    #[serde(skip)]
+    pub disabled_reason: Option<McpServerDisabledReason>,
+
+    /// Startup timeout in seconds for initializing MCP server & initially listing tools.
+    #[serde(
+        default,
+        with = "option_duration_secs",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub startup_timeout_sec: Option<Duration>,
+
+    /// Default timeout for MCP tool calls initiated via this server.
+    #[serde(default, with = "option_duration_secs")]
+    pub tool_timeout_sec: Option<Duration>,
+
+    /// Explicit allow-list of tools exposed from this server. When set, only these tools will be registered.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub enabled_tools: Option<Vec<String>>,
+
+    /// Explicit deny-list of tools. These tools will be removed after applying `enabled_tools`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub disabled_tools: Option<Vec<String>>,
+
+    /// Optional OAuth scopes to request during MCP login.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub scopes: Option<Vec<String>>,
+
+    /// Optional OAuth resource parameter to include during MCP login (RFC 8707).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub oauth_resource: Option<String>,
+
+    /// Per-tool approval settings keyed by tool name.
+    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
+    pub tools: HashMap<String, McpServerToolConfig>,
+}
+
+/// Raw MCP config shape used for deserialization and JSON Schema generation.
+///
+/// Keep `TryFrom<RawMcpServerConfig> for McpServerConfig` exhaustively
+/// destructuring this struct so new TOML fields cannot be added here without
+/// updating the validation/mapping logic that produces [`McpServerConfig`].
+#[derive(Deserialize, Clone, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct RawMcpServerConfig {
+    // stdio
+    pub command: Option<String>,
+    #[serde(default)]
+    pub args: Option<Vec<String>>,
+    #[serde(default)]
+    pub env: Option<HashMap<String, String>>,
+    #[serde(default)]
+    pub env_vars: Option<Vec<String>>,
+    #[serde(default)]
+    pub cwd: Option<PathBuf>,
+    pub http_headers: Option<HashMap<String, String>>,
+    #[serde(default)]
+    pub env_http_headers: Option<HashMap<String, String>>,
+
+    // streamable_http
+    pub url: Option<String>,
+    pub bearer_token: Option<String>,
+    pub bearer_token_env_var: Option<String>,
+
+    // shared
+    #[serde(default)]
+    pub startup_timeout_sec: Option<f64>,
+    #[serde(default)]
+    pub startup_timeout_ms: Option<u64>,
+    #[serde(default, with = "option_duration_secs")]
+    #[schemars(with = "Option<f64>")]
+    pub tool_timeout_sec: Option<Duration>,
+    #[serde(default)]
+    pub enabled: Option<bool>,
+    #[serde(default)]
+    pub required: Option<bool>,
+    #[serde(default)]
+    pub enabled_tools: Option<Vec<String>>,
+    #[serde(default)]
+    pub disabled_tools: Option<Vec<String>>,
+    #[serde(default)]
+    pub scopes: Option<Vec<String>>,
+    #[serde(default)]
+    pub oauth_resource: Option<String>,
+    /// Legacy display-name field accepted for backward compatibility.
+    #[serde(default, rename = "name")]
+    pub _name: Option<String>,
+    #[serde(default)]
+    pub tools: Option<HashMap<String, McpServerToolConfig>>,
+}
+
+impl TryFrom<RawMcpServerConfig> for McpServerConfig {
+    type Error = String;
+
+    fn try_from(raw: RawMcpServerConfig) -> Result<Self, Self::Error> {
+        let RawMcpServerConfig {
+            command,
+            args,
+            env,
+            env_vars,
+            cwd,
+            http_headers,
+            env_http_headers,
+            url,
+            bearer_token,
+            bearer_token_env_var,
+            startup_timeout_sec,
+            startup_timeout_ms,
+            tool_timeout_sec,
+            enabled,
+            required,
+            enabled_tools,
+            disabled_tools,
+            scopes,
+            oauth_resource,
+            _name: _,
+            tools,
+        } = raw;
+
+        let startup_timeout_sec = match (startup_timeout_sec, startup_timeout_ms) {
+            (Some(sec), _) => {
+                Some(Duration::try_from_secs_f64(sec).map_err(|err| err.to_string())?)
+            }
+            (None, Some(ms)) => Some(Duration::from_millis(ms)),
+            (None, None) => None,
+        };
+
+        fn throw_if_set<T>(transport: &str, field: &str, value: Option<&T>) -> Result<(), String> {
+            if value.is_none() {
+                return Ok(());
+            }
+            Err(format!("{field} is not supported for {transport}"))
+        }
+
+        let transport = if let Some(command) = command {
+            throw_if_set("stdio", "url", url.as_ref())?;
+            throw_if_set(
+                "stdio",
+                "bearer_token_env_var",
+                bearer_token_env_var.as_ref(),
+            )?;
+            throw_if_set("stdio", "bearer_token", bearer_token.as_ref())?;
+            throw_if_set("stdio", "http_headers", http_headers.as_ref())?;
+            throw_if_set("stdio", "env_http_headers", env_http_headers.as_ref())?;
+            throw_if_set("stdio", "oauth_resource", oauth_resource.as_ref())?;
+            McpServerTransportConfig::Stdio {
+                command,
+                args: args.unwrap_or_default(),
+                env,
+                env_vars: env_vars.unwrap_or_default(),
+                cwd,
+            }
+        } else if let Some(url) = url {
+            throw_if_set("streamable_http", "args", args.as_ref())?;
+            throw_if_set("streamable_http", "env", env.as_ref())?;
+            throw_if_set("streamable_http", "env_vars", env_vars.as_ref())?;
+            throw_if_set("streamable_http", "cwd", cwd.as_ref())?;
+            throw_if_set("streamable_http", "bearer_token", bearer_token.as_ref())?;
+            McpServerTransportConfig::StreamableHttp {
+                url,
+                bearer_token_env_var,
+                http_headers,
+                env_http_headers,
+            }
+        } else {
+            return Err("invalid transport".to_string());
+        };
+
+        Ok(Self {
+            transport,
+            startup_timeout_sec,
+            tool_timeout_sec,
+            enabled: enabled.unwrap_or_else(default_enabled),
+            required: required.unwrap_or_default(),
+            disabled_reason: None,
+            enabled_tools,
+            disabled_tools,
+            scopes,
+            oauth_resource,
+            tools: tools.unwrap_or_default(),
+        })
+    }
+}
+
+impl<'de> Deserialize<'de> for McpServerConfig {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        RawMcpServerConfig::deserialize(deserializer)?
+            .try_into()
+            .map_err(SerdeError::custom)
+    }
+}
+
+const fn default_enabled() -> bool {
+    true
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema)]
+#[serde(untagged, deny_unknown_fields, rename_all = "snake_case")]
+pub enum McpServerTransportConfig {
+    /// https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio
+    Stdio {
+        command: String,
+        #[serde(default)]
+        args: Vec<String>,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        env: Option<HashMap<String, String>>,
+        #[serde(default, skip_serializing_if = "Vec::is_empty")]
+        env_vars: Vec<String>,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        cwd: Option<PathBuf>,
+    },
+    /// https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http
+    StreamableHttp {
+        url: String,
+        /// Name of the environment variable to read for an HTTP bearer token.
+        /// When set, requests will include the token via `Authorization: Bearer <token>`.
+        /// The actual secret value must be provided via the environment.
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        bearer_token_env_var: Option<String>,
+        /// Additional HTTP headers to include in requests to this server.
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        http_headers: Option<HashMap<String, String>>,
+        /// HTTP headers where the value is sourced from an environment variable.
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        env_http_headers: Option<HashMap<String, String>>,
+    },
+}
+
+mod option_duration_secs {
+    use serde::Deserialize;
+    use serde::Deserializer;
+    use serde::Serializer;
+    use std::time::Duration;
+
+    pub fn serialize<S>(value: &Option<Duration>, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        match value {
+            Some(duration) => serializer.serialize_some(&duration.as_secs_f64()),
+            None => serializer.serialize_none(),
+        }
+    }
+
+    pub fn deserialize<'de, D>(deserializer: D) -> Result<Option<Duration>, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        let secs = Option::<f64>::deserialize(deserializer)?;
+        secs.map(|secs| Duration::try_from_secs_f64(secs).map_err(serde::de::Error::custom))
+            .transpose()
+    }
+}
+
+#[cfg(test)]
+#[path = "mcp_types_tests.rs"]
+mod tests;

codex-rs/config/src/mcp_types_tests.rs

@@ -0,0 +1,351 @@
+use super::*;
+use pretty_assertions::assert_eq;
+use std::collections::HashMap;
+use std::path::PathBuf;
+
+#[test]
+fn deserialize_stdio_command_server_config() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            command = "echo"
+        "#,
+    )
+    .expect("should deserialize command config");
+
+    assert_eq!(
+        cfg.transport,
+        McpServerTransportConfig::Stdio {
+            command: "echo".to_string(),
+            args: vec![],
+            env: None,
+            env_vars: Vec::new(),
+            cwd: None,
+        }
+    );
+    assert!(cfg.enabled);
+    assert!(!cfg.required);
+    assert!(cfg.enabled_tools.is_none());
+    assert!(cfg.disabled_tools.is_none());
+}
+
+#[test]
+fn deserialize_stdio_command_server_config_with_args() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            command = "echo"
+            args = ["hello", "world"]
+        "#,
+    )
+    .expect("should deserialize command config");
+
+    assert_eq!(
+        cfg.transport,
+        McpServerTransportConfig::Stdio {
+            command: "echo".to_string(),
+            args: vec!["hello".to_string(), "world".to_string()],
+            env: None,
+            env_vars: Vec::new(),
+            cwd: None,
+        }
+    );
+    assert!(cfg.enabled);
+}
+
+#[test]
+fn deserialize_stdio_command_server_config_with_arg_with_args_and_env() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            command = "echo"
+            args = ["hello", "world"]
+            env = { "FOO" = "BAR" }
+        "#,
+    )
+    .expect("should deserialize command config");
+
+    assert_eq!(
+        cfg.transport,
+        McpServerTransportConfig::Stdio {
+            command: "echo".to_string(),
+            args: vec!["hello".to_string(), "world".to_string()],
+            env: Some(HashMap::from([("FOO".to_string(), "BAR".to_string())])),
+            env_vars: Vec::new(),
+            cwd: None,
+        }
+    );
+    assert!(cfg.enabled);
+}
+
+#[test]
+fn deserialize_stdio_command_server_config_with_env_vars() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            command = "echo"
+            env_vars = ["FOO", "BAR"]
+        "#,
+    )
+    .expect("should deserialize command config with env_vars");
+
+    assert_eq!(
+        cfg.transport,
+        McpServerTransportConfig::Stdio {
+            command: "echo".to_string(),
+            args: vec![],
+            env: None,
+            env_vars: vec!["FOO".to_string(), "BAR".to_string()],
+            cwd: None,
+        }
+    );
+}
+
+#[test]
+fn deserialize_stdio_command_server_config_with_cwd() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            command = "echo"
+            cwd = "/tmp"
+        "#,
+    )
+    .expect("should deserialize command config with cwd");
+
+    assert_eq!(
+        cfg.transport,
+        McpServerTransportConfig::Stdio {
+            command: "echo".to_string(),
+            args: vec![],
+            env: None,
+            env_vars: Vec::new(),
+            cwd: Some(PathBuf::from("/tmp")),
+        }
+    );
+}
+
+#[test]
+fn deserialize_disabled_server_config() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            command = "echo"
+            enabled = false
+        "#,
+    )
+    .expect("should deserialize disabled server config");
+
+    assert!(!cfg.enabled);
+    assert!(!cfg.required);
+}
+
+#[test]
+fn deserialize_required_server_config() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            command = "echo"
+            required = true
+        "#,
+    )
+    .expect("should deserialize required server config");
+
+    assert!(cfg.required);
+}
+
+#[test]
+fn deserialize_streamable_http_server_config() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            url = "https://example.com/mcp"
+        "#,
+    )
+    .expect("should deserialize http config");
+
+    assert_eq!(
+        cfg.transport,
+        McpServerTransportConfig::StreamableHttp {
+            url: "https://example.com/mcp".to_string(),
+            bearer_token_env_var: None,
+            http_headers: None,
+            env_http_headers: None,
+        }
+    );
+    assert!(cfg.enabled);
+}
+
+#[test]
+fn deserialize_streamable_http_server_config_with_env_var() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            url = "https://example.com/mcp"
+            bearer_token_env_var = "GITHUB_TOKEN"
+        "#,
+    )
+    .expect("should deserialize http config");
+
+    assert_eq!(
+        cfg.transport,
+        McpServerTransportConfig::StreamableHttp {
+            url: "https://example.com/mcp".to_string(),
+            bearer_token_env_var: Some("GITHUB_TOKEN".to_string()),
+            http_headers: None,
+            env_http_headers: None,
+        }
+    );
+    assert!(cfg.enabled);
+}
+
+#[test]
+fn deserialize_streamable_http_server_config_with_headers() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            url = "https://example.com/mcp"
+            http_headers = { "X-Foo" = "bar" }
+            env_http_headers = { "X-Token" = "TOKEN_ENV" }
+        "#,
+    )
+    .expect("should deserialize http config with headers");
+
+    assert_eq!(
+        cfg.transport,
+        McpServerTransportConfig::StreamableHttp {
+            url: "https://example.com/mcp".to_string(),
+            bearer_token_env_var: None,
+            http_headers: Some(HashMap::from([("X-Foo".to_string(), "bar".to_string())])),
+            env_http_headers: Some(HashMap::from([(
+                "X-Token".to_string(),
+                "TOKEN_ENV".to_string()
+            )])),
+        }
+    );
+}
+
+#[test]
+fn deserialize_streamable_http_server_config_with_oauth_resource() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            url = "https://example.com/mcp"
+            oauth_resource = "https://api.example.com"
+        "#,
+    )
+    .expect("should deserialize http config with oauth_resource");
+
+    assert_eq!(
+        cfg.oauth_resource,
+        Some("https://api.example.com".to_string())
+    );
+}
+
+#[test]
+fn deserialize_server_config_with_tool_filters() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            command = "echo"
+            enabled_tools = ["allowed"]
+            disabled_tools = ["blocked"]
+        "#,
+    )
+    .expect("should deserialize tool filters");
+
+    assert_eq!(cfg.enabled_tools, Some(vec!["allowed".to_string()]));
+    assert_eq!(cfg.disabled_tools, Some(vec!["blocked".to_string()]));
+}
+
+#[test]
+fn deserialize_ignores_unknown_server_fields() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            command = "echo"
+            trust_level = "trusted"
+        "#,
+    )
+    .expect("should ignore unknown server fields");
+
+    assert_eq!(
+        cfg,
+        McpServerConfig {
+            transport: McpServerTransportConfig::Stdio {
+                command: "echo".to_string(),
+                args: vec![],
+                env: None,
+                env_vars: Vec::new(),
+                cwd: None,
+            },
+            enabled: true,
+            required: false,
+            disabled_reason: None,
+            startup_timeout_sec: None,
+            tool_timeout_sec: None,
+            enabled_tools: None,
+            disabled_tools: None,
+            scopes: None,
+            oauth_resource: None,
+            tools: HashMap::new(),
+        }
+    );
+}
+
+#[test]
+fn deserialize_rejects_command_and_url() {
+    toml::from_str::<McpServerConfig>(
+        r#"
+            command = "echo"
+            url = "https://example.com"
+        "#,
+    )
+    .expect_err("should reject command+url");
+}
+
+#[test]
+fn deserialize_rejects_env_for_http_transport() {
+    toml::from_str::<McpServerConfig>(
+        r#"
+            url = "https://example.com"
+            env = { "FOO" = "BAR" }
+        "#,
+    )
+    .expect_err("should reject env for http transport");
+}
+
+#[test]
+fn deserialize_rejects_headers_for_stdio() {
+    toml::from_str::<McpServerConfig>(
+        r#"
+            command = "echo"
+            http_headers = { "X-Foo" = "bar" }
+        "#,
+    )
+    .expect_err("should reject http_headers for stdio transport");
+
+    toml::from_str::<McpServerConfig>(
+        r#"
+            command = "echo"
+            env_http_headers = { "X-Foo" = "BAR_ENV" }
+        "#,
+    )
+    .expect_err("should reject env_http_headers for stdio transport");
+
+    let err = toml::from_str::<McpServerConfig>(
+        r#"
+            command = "echo"
+            oauth_resource = "https://api.example.com"
+        "#,
+    )
+    .expect_err("should reject oauth_resource for stdio transport");
+
+    assert!(
+        err.to_string()
+            .contains("oauth_resource is not supported for stdio"),
+        "unexpected error: {err}"
+    );
+}
+
+#[test]
+fn deserialize_rejects_inline_bearer_token_field() {
+    let err = toml::from_str::<McpServerConfig>(
+        r#"
+            url = "https://example.com"
+            bearer_token = "secret"
+        "#,
+    )
+    .expect_err("should reject bearer_token field");
+
+    assert!(
+        err.to_string().contains("bearer_token is not supported"),
+        "unexpected error: {err}"
+    );
+}

codex-rs/core/Cargo.toml

@@ -38,6 +38,7 @@ codex-core-skills = { workspace = true }
 codex-exec-server = { workspace = true }
 codex-features = { workspace = true }
 codex-login = { workspace = true }
+codex-mcp = { workspace = true }
 codex-shell-command = { workspace = true }
 codex-execpolicy = { workspace = true }
 codex-git-utils = { workspace = true }

codex-rs/core/config.schema.json

@@ -1319,6 +1319,7 @@
     },
     "RawMcpServerConfig": {
       "additionalProperties": false,
+      "description": "Raw MCP config shape used for deserialization and JSON Schema generation.\n\nKeep `TryFrom<RawMcpServerConfig> for McpServerConfig` exhaustively destructuring this struct so new TOML fields cannot be added here without updating the validation/mapping logic that produces [`McpServerConfig`].",
       "properties": {
         "args": {
           "default": null,
@@ -2626,4 +2627,4 @@
   },
   "title": "ConfigToml",
   "type": "object"
-}
+}

codex-rs/core/src/codex.rs

@@ -265,11 +265,11 @@ use crate::instructions::UserInstructions;
 use crate::mcp::CODEX_APPS_MCP_SERVER_NAME;
 use crate::mcp::McpManager;
 use crate::mcp::auth::compute_auth_statuses;
-use crate::mcp::maybe_prompt_and_install_mcp_dependencies;
 use crate::mcp::with_codex_apps_mcp;
 use crate::mcp_connection_manager::McpConnectionManager;
 use crate::mcp_connection_manager::codex_apps_tools_cache_key;
 use crate::mcp_connection_manager::filter_non_codex_apps_mcp_tools_only;
+use crate::mcp_skill_dependencies::maybe_prompt_and_install_mcp_dependencies;
 use crate::memories;
 use crate::mentions::build_connector_slug_counts;
 use crate::mentions::build_skill_name_counts;
@@ -2000,6 +2000,7 @@ impl Session {
             config.mcp_oauth_credentials_store_mode,
             auth_statuses.clone(),
             &session_configuration.approval_policy,
+            INITIAL_SUBMIT_ID.to_owned(),
             tx_event.clone(),
             sandbox_state,
             config.codex_home.clone(),
@@ -4250,16 +4251,12 @@ impl Session {
     ) {
         let auth = self.services.auth_manager.auth().await;
         let config = self.get_config().await;
+        let mcp_config = config.to_mcp_config(self.services.plugins_manager.as_ref());
         let tool_plugin_provenance = self
             .services
             .mcp_manager
             .tool_plugin_provenance(config.as_ref());
-        let mcp_servers = with_codex_apps_mcp(
-            mcp_servers,
-            self.features.apps_enabled_for_auth(auth.as_ref()),
-            auth.as_ref(),
-            config.as_ref(),
-        );
+        let mcp_servers = with_codex_apps_mcp(mcp_servers, auth.as_ref(), &mcp_config);
         let auth_statuses = compute_auth_statuses(mcp_servers.iter(), store_mode).await;
         let sandbox_state = SandboxState {
             sandbox_policy: turn_context.sandbox_policy.get().clone(),
@@ -4277,6 +4274,7 @@ impl Session {
             store_mode,
             auth_statuses,
             &turn_context.config.permissions.approval_policy,
+            turn_context.sub_id.clone(),
             self.get_tx_event(),
             sandbox_state,
             config.codex_home.clone(),
@@ -4619,8 +4617,6 @@ mod handlers {
     use codex_features::Feature;
     use codex_utils_absolute_path::AbsolutePathBuf;
 
-    use crate::mcp::auth::compute_auth_statuses;
-    use crate::mcp::collect_mcp_snapshot_from_manager;
     use crate::review_prompts::resolve_review_request;
     use crate::rollout::RolloutRecorder;
     use crate::rollout::session_index;
@@ -4629,6 +4625,8 @@ mod handlers {
     use crate::tasks::UserShellCommandMode;
     use crate::tasks::UserShellCommandTask;
     use crate::tasks::execute_user_shell_command;
+    use codex_mcp::mcp::auth::compute_auth_statuses;
+    use codex_mcp::mcp::collect_mcp_snapshot_from_manager;
     use codex_protocol::protocol::CodexErrorInfo;
     use codex_protocol::protocol::ErrorEvent;
     use codex_protocol::protocol::Event;

codex-rs/core/src/codex_tests.rs

@@ -2654,11 +2654,9 @@ pub(crate) async fn make_session_and_context() -> (Session, TurnContext) {
 
     let skills_watcher = Arc::new(SkillsWatcher::noop());
     let services = SessionServices {
-        mcp_connection_manager: Arc::new(RwLock::new(
-            McpConnectionManager::new_mcp_connection_manager_for_tests(
-                &config.permissions.approval_policy,
-            ),
-        )),
+        mcp_connection_manager: Arc::new(RwLock::new(McpConnectionManager::new_uninitialized(
+            &config.permissions.approval_policy,
+        ))),
         mcp_startup_cancellation_token: Mutex::new(CancellationToken::new()),
         unified_exec_manager: UnifiedExecProcessManager::new(
             config.background_terminal_max_timeout,
@@ -3497,11 +3495,9 @@ pub(crate) async fn make_session_and_context_with_dynamic_tools_and_rx(
 
     let skills_watcher = Arc::new(SkillsWatcher::noop());
     let services = SessionServices {
-        mcp_connection_manager: Arc::new(RwLock::new(
-            McpConnectionManager::new_mcp_connection_manager_for_tests(
-                &config.permissions.approval_policy,
-            ),
-        )),
+        mcp_connection_manager: Arc::new(RwLock::new(McpConnectionManager::new_uninitialized(
+            &config.permissions.approval_policy,
+        ))),
         mcp_startup_cancellation_token: Mutex::new(CancellationToken::new()),
         unified_exec_manager: UnifiedExecProcessManager::new(
             config.background_terminal_max_timeout,

codex-rs/core/src/config/config_tests.rs

@@ -15,6 +15,7 @@ use crate::config::types::NotificationMethod;
 use crate::config::types::Notifications;
 use crate::config::types::ToolSuggestDiscoverableType;
 use crate::config_loader::RequirementSource;
+use crate::plugins::PluginsManager;
 use assert_matches::assert_matches;
 use codex_config::CONFIG_TOML_FILE;
 use codex_features::Feature;
@@ -2067,6 +2068,30 @@ approval_mode = "approve"
     );
 }
 
+#[test]
+fn to_mcp_config_preserves_apps_feature_from_config() -> std::io::Result<()> {
+    let codex_home = TempDir::new()?;
+    let mut config = Config::load_from_base_config_with_overrides(
+        ConfigToml::default(),
+        ConfigOverrides::default(),
+        codex_home.path().to_path_buf(),
+    )?;
+    let plugins_manager = PluginsManager::new(codex_home.path().to_path_buf());
+
+    let mcp_config = config.to_mcp_config(&plugins_manager);
+    assert!(mcp_config.apps_enabled);
+
+    let _ = config.features.disable(Feature::Apps);
+    let mcp_config = config.to_mcp_config(&plugins_manager);
+    assert!(!mcp_config.apps_enabled);
+
+    let _ = config.features.enable(Feature::Apps);
+    let mcp_config = config.to_mcp_config(&plugins_manager);
+    assert!(mcp_config.apps_enabled);
+
+    Ok(())
+}
+
 #[tokio::test]
 async fn load_global_mcp_servers_rejects_inline_bearer_token() -> anyhow::Result<()> {
     let codex_home = TempDir::new()?;

codex-rs/core/src/config/mod.rs

@@ -66,6 +66,7 @@ use codex_features::FeatureOverrides;
 use codex_features::Features;
 use codex_features::FeaturesToml;
 use codex_git_utils::resolve_root_git_project_for_trust;
+use codex_mcp::mcp::McpConfig;
 use codex_protocol::config_types::AltScreenMode;
 use codex_protocol::config_types::ForcedLoginMethod;
 use codex_protocol::config_types::Personality;
@@ -683,6 +684,31 @@ impl ConfigBuilder {
 }
 
 impl Config {
+    pub fn to_mcp_config(&self, plugins_manager: &crate::plugins::PluginsManager) -> McpConfig {
+        let loaded_plugins = plugins_manager.plugins_for_config(self);
+        let mut configured_mcp_servers = self.mcp_servers.get().clone();
+        for (name, plugin_server) in loaded_plugins.effective_mcp_servers() {
+            configured_mcp_servers.entry(name).or_insert(plugin_server);
+        }
+
+        McpConfig {
+            chatgpt_base_url: self.chatgpt_base_url.clone(),
+            codex_home: self.codex_home.clone(),
+            mcp_oauth_credentials_store_mode: self.mcp_oauth_credentials_store_mode,
+            mcp_oauth_callback_port: self.mcp_oauth_callback_port,
+            mcp_oauth_callback_url: self.mcp_oauth_callback_url.clone(),
+            skill_mcp_dependency_install_enabled: self
+                .features
+                .enabled(Feature::SkillMcpDependencyInstall),
+            approval_policy: self.permissions.approval_policy.clone(),
+            codex_linux_sandbox_exe: self.codex_linux_sandbox_exe.clone(),
+            use_legacy_landlock: self.features.use_legacy_landlock(),
+            apps_enabled: self.features.enabled(Feature::Apps),
+            configured_mcp_servers,
+            plugin_capability_summaries: loaded_plugins.capability_summaries().to_vec(),
+        }
+    }
+
     /// This is the preferred way to create an instance of [Config].
     pub async fn load_with_cli_overrides(
         cli_overrides: Vec<(String, TomlValue)>,

codex-rs/core/src/config/types.rs

@@ -3,7 +3,12 @@
 // Note this file should generally be restricted to simple struct/enum
 // definitions that do not contain business logic.
 
-use crate::config_loader::RequirementSource;
+pub use codex_config::AppToolApproval;
+pub use codex_config::McpServerConfig;
+pub use codex_config::McpServerDisabledReason;
+pub use codex_config::McpServerToolConfig;
+pub use codex_config::McpServerTransportConfig;
+pub use codex_config::RawMcpServerConfig;
 pub use codex_protocol::config_types::AltScreenMode;
 pub use codex_protocol::config_types::ApprovalsReviewer;
 pub use codex_protocol::config_types::ModeKind;
@@ -14,15 +19,11 @@ use codex_utils_absolute_path::AbsolutePathBuf;
 use std::collections::BTreeMap;
 use std::collections::HashMap;
 use std::fmt;
-use std::path::PathBuf;
-use std::time::Duration;
 use wildmatch::WildMatchPattern;
 
 use schemars::JsonSchema;
 use serde::Deserialize;
-use serde::Deserializer;
 use serde::Serialize;
-use serde::de::Error as SerdeError;
 
 pub const DEFAULT_OTEL_ENVIRONMENT: &str = "dev";
 pub const DEFAULT_MEMORIES_MAX_ROLLOUTS_PER_STARTUP: usize = 16;
@@ -31,6 +32,10 @@ pub const DEFAULT_MEMORIES_MIN_ROLLOUT_IDLE_HOURS: i64 = 6;
 pub const DEFAULT_MEMORIES_MAX_RAW_MEMORIES_FOR_CONSOLIDATION: usize = 256;
 pub const DEFAULT_MEMORIES_MAX_UNUSED_DAYS: i64 = 30;
 
+const fn default_enabled() -> bool {
+    true
+}
+
 #[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, JsonSchema)]
 #[serde(rename_all = "kebab-case")]
 pub enum WindowsSandboxModeToml {
@@ -47,272 +52,6 @@ pub struct WindowsToml {
     pub sandbox_private_desktop: Option<bool>,
 }
 
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub enum McpServerDisabledReason {
-    Unknown,
-    Requirements { source: RequirementSource },
-}
-
-impl fmt::Display for McpServerDisabledReason {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        match self {
-            McpServerDisabledReason::Unknown => write!(f, "unknown"),
-            McpServerDisabledReason::Requirements { source } => {
-                write!(f, "requirements ({source})")
-            }
-        }
-    }
-}
-
-#[derive(Serialize, Debug, Clone, PartialEq)]
-pub struct McpServerConfig {
-    #[serde(flatten)]
-    pub transport: McpServerTransportConfig,
-
-    /// When `false`, Codex skips initializing this MCP server.
-    #[serde(default = "default_enabled")]
-    pub enabled: bool,
-
-    /// When `true`, `codex exec` exits with an error if this MCP server fails to initialize.
-    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
-    pub required: bool,
-
-    /// Reason this server was disabled after applying requirements.
-    #[serde(skip)]
-    pub disabled_reason: Option<McpServerDisabledReason>,
-
-    /// Startup timeout in seconds for initializing MCP server & initially listing tools.
-    #[serde(
-        default,
-        with = "option_duration_secs",
-        skip_serializing_if = "Option::is_none"
-    )]
-    pub startup_timeout_sec: Option<Duration>,
-
-    /// Default timeout for MCP tool calls initiated via this server.
-    #[serde(default, with = "option_duration_secs")]
-    pub tool_timeout_sec: Option<Duration>,
-
-    /// Explicit allow-list of tools exposed from this server. When set, only these tools will be registered.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub enabled_tools: Option<Vec<String>>,
-
-    /// Explicit deny-list of tools. These tools will be removed after applying `enabled_tools`.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub disabled_tools: Option<Vec<String>>,
-
-    /// Optional OAuth scopes to request during MCP login.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub scopes: Option<Vec<String>>,
-
-    /// Optional OAuth resource parameter to include during MCP login (RFC 8707).
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub oauth_resource: Option<String>,
-
-    /// Per-tool approval settings keyed by tool name.
-    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
-    pub tools: HashMap<String, McpServerToolConfig>,
-}
-
-// Raw MCP config shape used for deserialization and JSON Schema generation.
-// Keep this in sync with the validation logic in `McpServerConfig`.
-#[derive(Deserialize, Clone, JsonSchema)]
-#[schemars(deny_unknown_fields)]
-pub(crate) struct RawMcpServerConfig {
-    // stdio
-    pub command: Option<String>,
-    #[serde(default)]
-    pub args: Option<Vec<String>>,
-    #[serde(default)]
-    pub env: Option<HashMap<String, String>>,
-    #[serde(default)]
-    pub env_vars: Option<Vec<String>>,
-    #[serde(default)]
-    pub cwd: Option<PathBuf>,
-    pub http_headers: Option<HashMap<String, String>>,
-    #[serde(default)]
-    pub env_http_headers: Option<HashMap<String, String>>,
-
-    // streamable_http
-    pub url: Option<String>,
-    pub bearer_token: Option<String>,
-    pub bearer_token_env_var: Option<String>,
-
-    // shared
-    #[serde(default)]
-    pub startup_timeout_sec: Option<f64>,
-    #[serde(default)]
-    pub startup_timeout_ms: Option<u64>,
-    #[serde(default, with = "option_duration_secs")]
-    #[schemars(with = "Option<f64>")]
-    pub tool_timeout_sec: Option<Duration>,
-    #[serde(default)]
-    pub enabled: Option<bool>,
-    #[serde(default)]
-    pub required: Option<bool>,
-    #[serde(default)]
-    pub enabled_tools: Option<Vec<String>>,
-    #[serde(default)]
-    pub disabled_tools: Option<Vec<String>>,
-    #[serde(default)]
-    pub scopes: Option<Vec<String>>,
-    #[serde(default)]
-    pub oauth_resource: Option<String>,
-    /// Legacy display-name field accepted for backward compatibility.
-    #[serde(default, rename = "name")]
-    pub _name: Option<String>,
-    #[serde(default)]
-    pub tools: Option<HashMap<String, McpServerToolConfig>>,
-}
-
-impl<'de> Deserialize<'de> for McpServerConfig {
-    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
-    where
-        D: Deserializer<'de>,
-    {
-        let mut raw = RawMcpServerConfig::deserialize(deserializer)?;
-
-        let startup_timeout_sec = match (raw.startup_timeout_sec, raw.startup_timeout_ms) {
-            (Some(sec), _) => {
-                let duration = Duration::try_from_secs_f64(sec).map_err(SerdeError::custom)?;
-                Some(duration)
-            }
-            (None, Some(ms)) => Some(Duration::from_millis(ms)),
-            (None, None) => None,
-        };
-        let tool_timeout_sec = raw.tool_timeout_sec;
-        let enabled = raw.enabled.unwrap_or_else(default_enabled);
-        let required = raw.required.unwrap_or_default();
-        let enabled_tools = raw.enabled_tools.clone();
-        let disabled_tools = raw.disabled_tools.clone();
-        let scopes = raw.scopes.clone();
-        let oauth_resource = raw.oauth_resource.clone();
-        let tools = raw.tools.clone().unwrap_or_default();
-
-        fn throw_if_set<E, T>(transport: &str, field: &str, value: Option<&T>) -> Result<(), E>
-        where
-            E: SerdeError,
-        {
-            if value.is_none() {
-                return Ok(());
-            }
-            Err(E::custom(format!(
-                "{field} is not supported for {transport}",
-            )))
-        }
-
-        let transport = if let Some(command) = raw.command.clone() {
-            throw_if_set("stdio", "url", raw.url.as_ref())?;
-            throw_if_set(
-                "stdio",
-                "bearer_token_env_var",
-                raw.bearer_token_env_var.as_ref(),
-            )?;
-            throw_if_set("stdio", "bearer_token", raw.bearer_token.as_ref())?;
-            throw_if_set("stdio", "http_headers", raw.http_headers.as_ref())?;
-            throw_if_set("stdio", "env_http_headers", raw.env_http_headers.as_ref())?;
-            throw_if_set("stdio", "oauth_resource", raw.oauth_resource.as_ref())?;
-            McpServerTransportConfig::Stdio {
-                command,
-                args: raw.args.clone().unwrap_or_default(),
-                env: raw.env.clone(),
-                env_vars: raw.env_vars.clone().unwrap_or_default(),
-                cwd: raw.cwd.take(),
-            }
-        } else if let Some(url) = raw.url.clone() {
-            throw_if_set("streamable_http", "args", raw.args.as_ref())?;
-            throw_if_set("streamable_http", "env", raw.env.as_ref())?;
-            throw_if_set("streamable_http", "env_vars", raw.env_vars.as_ref())?;
-            throw_if_set("streamable_http", "cwd", raw.cwd.as_ref())?;
-            throw_if_set("streamable_http", "bearer_token", raw.bearer_token.as_ref())?;
-            McpServerTransportConfig::StreamableHttp {
-                url,
-                bearer_token_env_var: raw.bearer_token_env_var.clone(),
-                http_headers: raw.http_headers.clone(),
-                env_http_headers: raw.env_http_headers.take(),
-            }
-        } else {
-            return Err(SerdeError::custom("invalid transport"));
-        };
-
-        Ok(Self {
-            transport,
-            startup_timeout_sec,
-            tool_timeout_sec,
-            enabled,
-            required,
-            disabled_reason: None,
-            enabled_tools,
-            disabled_tools,
-            scopes,
-            oauth_resource,
-            tools,
-        })
-    }
-}
-
-const fn default_enabled() -> bool {
-    true
-}
-
-#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema)]
-#[serde(untagged, deny_unknown_fields, rename_all = "snake_case")]
-pub enum McpServerTransportConfig {
-    /// https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio
-    Stdio {
-        command: String,
-        #[serde(default)]
-        args: Vec<String>,
-        #[serde(default, skip_serializing_if = "Option::is_none")]
-        env: Option<HashMap<String, String>>,
-        #[serde(default, skip_serializing_if = "Vec::is_empty")]
-        env_vars: Vec<String>,
-        #[serde(default, skip_serializing_if = "Option::is_none")]
-        cwd: Option<PathBuf>,
-    },
-    /// https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http
-    StreamableHttp {
-        url: String,
-        /// Name of the environment variable to read for an HTTP bearer token.
-        /// When set, requests will include the token via `Authorization: Bearer <token>`.
-        /// The actual secret value must be provided via the environment.
-        #[serde(default, skip_serializing_if = "Option::is_none")]
-        bearer_token_env_var: Option<String>,
-        /// Additional HTTP headers to include in requests to this server.
-        #[serde(default, skip_serializing_if = "Option::is_none")]
-        http_headers: Option<HashMap<String, String>>,
-        /// HTTP headers where the value is sourced from an environment variable.
-        #[serde(default, skip_serializing_if = "Option::is_none")]
-        env_http_headers: Option<HashMap<String, String>>,
-    },
-}
-
-mod option_duration_secs {
-    use serde::Deserialize;
-    use serde::Deserializer;
-    use serde::Serializer;
-    use std::time::Duration;
-
-    pub fn serialize<S>(value: &Option<Duration>, serializer: S) -> Result<S::Ok, S::Error>
-    where
-        S: Serializer,
-    {
-        match value {
-            Some(duration) => serializer.serialize_some(&duration.as_secs_f64()),
-            None => serializer.serialize_none(),
-        }
-    }
-
-    pub fn deserialize<'de, D>(deserializer: D) -> Result<Option<Duration>, D::Error>
-    where
-        D: Deserializer<'de>,
-    {
-        let secs = Option::<f64>::deserialize(deserializer)?;
-        secs.map(|secs| Duration::try_from_secs_f64(secs).map_err(serde::de::Error::custom))
-            .transpose()
-    }
-}
-
 #[derive(Serialize, Deserialize, Debug, Copy, Clone, PartialEq, JsonSchema)]
 pub enum UriBasedFileOpener {
     #[serde(rename = "vscode")]
@@ -498,24 +237,6 @@ impl From<MemoriesToml> for MemoriesConfig {
     }
 }
 
-#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, Default, JsonSchema)]
-#[serde(rename_all = "snake_case")]
-pub enum AppToolApproval {
-    #[default]
-    Auto,
-    Prompt,
-    Approve,
-}
-
-/// Per-tool approval settings for a single MCP server tool.
-#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Default, JsonSchema)]
-#[schemars(deny_unknown_fields)]
-pub struct McpServerToolConfig {
-    /// Approval mode for this tool.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub approval_mode: Option<AppToolApproval>,
-}
-
 /// Default settings that apply to all apps.
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Default, JsonSchema)]
 #[schemars(deny_unknown_fields)]

codex-rs/core/src/config/types_tests.rs

@@ -1,282 +1,6 @@
 use super::*;
 use pretty_assertions::assert_eq;
 
-#[test]
-fn deserialize_stdio_command_server_config() {
-    let cfg: McpServerConfig = toml::from_str(
-        r#"
-            command = "echo"
-        "#,
-    )
-    .expect("should deserialize command config");
-
-    assert_eq!(
-        cfg.transport,
-        McpServerTransportConfig::Stdio {
-            command: "echo".to_string(),
-            args: vec![],
-            env: None,
-            env_vars: Vec::new(),
-            cwd: None,
-        }
-    );
-    assert!(cfg.enabled);
-    assert!(!cfg.required);
-    assert!(cfg.enabled_tools.is_none());
-    assert!(cfg.disabled_tools.is_none());
-}
-
-#[test]
-fn deserialize_stdio_command_server_config_with_args() {
-    let cfg: McpServerConfig = toml::from_str(
-        r#"
-            command = "echo"
-            args = ["hello", "world"]
-        "#,
-    )
-    .expect("should deserialize command config");
-
-    assert_eq!(
-        cfg.transport,
-        McpServerTransportConfig::Stdio {
-            command: "echo".to_string(),
-            args: vec!["hello".to_string(), "world".to_string()],
-            env: None,
-            env_vars: Vec::new(),
-            cwd: None,
-        }
-    );
-    assert!(cfg.enabled);
-}
-
-#[test]
-fn deserialize_stdio_command_server_config_with_arg_with_args_and_env() {
-    let cfg: McpServerConfig = toml::from_str(
-        r#"
-            command = "echo"
-            args = ["hello", "world"]
-            env = { "FOO" = "BAR" }
-        "#,
-    )
-    .expect("should deserialize command config");
-
-    assert_eq!(
-        cfg.transport,
-        McpServerTransportConfig::Stdio {
-            command: "echo".to_string(),
-            args: vec!["hello".to_string(), "world".to_string()],
-            env: Some(HashMap::from([("FOO".to_string(), "BAR".to_string())])),
-            env_vars: Vec::new(),
-            cwd: None,
-        }
-    );
-    assert!(cfg.enabled);
-}
-
-#[test]
-fn deserialize_stdio_command_server_config_with_env_vars() {
-    let cfg: McpServerConfig = toml::from_str(
-        r#"
-            command = "echo"
-            env_vars = ["FOO", "BAR"]
-        "#,
-    )
-    .expect("should deserialize command config with env_vars");
-
-    assert_eq!(
-        cfg.transport,
-        McpServerTransportConfig::Stdio {
-            command: "echo".to_string(),
-            args: vec![],
-            env: None,
-            env_vars: vec!["FOO".to_string(), "BAR".to_string()],
-            cwd: None,
-        }
-    );
-}
-
-#[test]
-fn deserialize_stdio_command_server_config_with_cwd() {
-    let cfg: McpServerConfig = toml::from_str(
-        r#"
-            command = "echo"
-            cwd = "/tmp"
-        "#,
-    )
-    .expect("should deserialize command config with cwd");
-
-    assert_eq!(
-        cfg.transport,
-        McpServerTransportConfig::Stdio {
-            command: "echo".to_string(),
-            args: vec![],
-            env: None,
-            env_vars: Vec::new(),
-            cwd: Some(PathBuf::from("/tmp")),
-        }
-    );
-}
-
-#[test]
-fn deserialize_disabled_server_config() {
-    let cfg: McpServerConfig = toml::from_str(
-        r#"
-            command = "echo"
-            enabled = false
-        "#,
-    )
-    .expect("should deserialize disabled server config");
-
-    assert!(!cfg.enabled);
-    assert!(!cfg.required);
-}
-
-#[test]
-fn deserialize_required_server_config() {
-    let cfg: McpServerConfig = toml::from_str(
-        r#"
-            command = "echo"
-            required = true
-        "#,
-    )
-    .expect("should deserialize required server config");
-
-    assert!(cfg.required);
-}
-
-#[test]
-fn deserialize_streamable_http_server_config() {
-    let cfg: McpServerConfig = toml::from_str(
-        r#"
-            url = "https://example.com/mcp"
-        "#,
-    )
-    .expect("should deserialize http config");
-
-    assert_eq!(
-        cfg.transport,
-        McpServerTransportConfig::StreamableHttp {
-            url: "https://example.com/mcp".to_string(),
-            bearer_token_env_var: None,
-            http_headers: None,
-            env_http_headers: None,
-        }
-    );
-    assert!(cfg.enabled);
-}
-
-#[test]
-fn deserialize_streamable_http_server_config_with_env_var() {
-    let cfg: McpServerConfig = toml::from_str(
-        r#"
-            url = "https://example.com/mcp"
-            bearer_token_env_var = "GITHUB_TOKEN"
-        "#,
-    )
-    .expect("should deserialize http config");
-
-    assert_eq!(
-        cfg.transport,
-        McpServerTransportConfig::StreamableHttp {
-            url: "https://example.com/mcp".to_string(),
-            bearer_token_env_var: Some("GITHUB_TOKEN".to_string()),
-            http_headers: None,
-            env_http_headers: None,
-        }
-    );
-    assert!(cfg.enabled);
-}
-
-#[test]
-fn deserialize_streamable_http_server_config_with_headers() {
-    let cfg: McpServerConfig = toml::from_str(
-        r#"
-            url = "https://example.com/mcp"
-            http_headers = { "X-Foo" = "bar" }
-            env_http_headers = { "X-Token" = "TOKEN_ENV" }
-        "#,
-    )
-    .expect("should deserialize http config with headers");
-
-    assert_eq!(
-        cfg.transport,
-        McpServerTransportConfig::StreamableHttp {
-            url: "https://example.com/mcp".to_string(),
-            bearer_token_env_var: None,
-            http_headers: Some(HashMap::from([("X-Foo".to_string(), "bar".to_string())])),
-            env_http_headers: Some(HashMap::from([(
-                "X-Token".to_string(),
-                "TOKEN_ENV".to_string()
-            )])),
-        }
-    );
-}
-
-#[test]
-fn deserialize_streamable_http_server_config_with_oauth_resource() {
-    let cfg: McpServerConfig = toml::from_str(
-        r#"
-            url = "https://example.com/mcp"
-            oauth_resource = "https://api.example.com"
-        "#,
-    )
-    .expect("should deserialize http config with oauth_resource");
-
-    assert_eq!(
-        cfg.oauth_resource,
-        Some("https://api.example.com".to_string())
-    );
-}
-
-#[test]
-fn deserialize_server_config_with_tool_filters() {
-    let cfg: McpServerConfig = toml::from_str(
-        r#"
-            command = "echo"
-            enabled_tools = ["allowed"]
-            disabled_tools = ["blocked"]
-        "#,
-    )
-    .expect("should deserialize tool filters");
-
-    assert_eq!(cfg.enabled_tools, Some(vec!["allowed".to_string()]));
-    assert_eq!(cfg.disabled_tools, Some(vec!["blocked".to_string()]));
-}
-
-#[test]
-fn deserialize_ignores_unknown_server_fields() {
-    let cfg: McpServerConfig = toml::from_str(
-        r#"
-            command = "echo"
-            trust_level = "trusted"
-        "#,
-    )
-    .expect("should ignore unknown server fields");
-
-    assert_eq!(
-        cfg,
-        McpServerConfig {
-            transport: McpServerTransportConfig::Stdio {
-                command: "echo".to_string(),
-                args: vec![],
-                env: None,
-                env_vars: Vec::new(),
-                cwd: None,
-            },
-            enabled: true,
-            required: false,
-            disabled_reason: None,
-            startup_timeout_sec: None,
-            tool_timeout_sec: None,
-            enabled_tools: None,
-            disabled_tools: None,
-            scopes: None,
-            oauth_resource: None,
-            tools: HashMap::new(),
-        }
-    );
-}
-
 #[test]
 fn deserialize_skill_config_with_name_selector() {
     let cfg: SkillConfig = toml::from_str(
@@ -317,74 +41,3 @@ fn deserialize_skill_config_with_path_selector() {
         }
     );
 }
-
-#[test]
-fn deserialize_rejects_command_and_url() {
-    toml::from_str::<McpServerConfig>(
-        r#"
-            command = "echo"
-            url = "https://example.com"
-        "#,
-    )
-    .expect_err("should reject command+url");
-}
-
-#[test]
-fn deserialize_rejects_env_for_http_transport() {
-    toml::from_str::<McpServerConfig>(
-        r#"
-            url = "https://example.com"
-            env = { "FOO" = "BAR" }
-        "#,
-    )
-    .expect_err("should reject env for http transport");
-}
-
-#[test]
-fn deserialize_rejects_headers_for_stdio() {
-    toml::from_str::<McpServerConfig>(
-        r#"
-            command = "echo"
-            http_headers = { "X-Foo" = "bar" }
-        "#,
-    )
-    .expect_err("should reject http_headers for stdio transport");
-
-    toml::from_str::<McpServerConfig>(
-        r#"
-            command = "echo"
-            env_http_headers = { "X-Foo" = "BAR_ENV" }
-        "#,
-    )
-    .expect_err("should reject env_http_headers for stdio transport");
-
-    let err = toml::from_str::<McpServerConfig>(
-        r#"
-            command = "echo"
-            oauth_resource = "https://api.example.com"
-        "#,
-    )
-    .expect_err("should reject oauth_resource for stdio transport");
-
-    assert!(
-        err.to_string()
-            .contains("oauth_resource is not supported for stdio"),
-        "unexpected error: {err}"
-    );
-}
-
-#[test]
-fn deserialize_rejects_inline_bearer_token_field() {
-    let err = toml::from_str::<McpServerConfig>(
-        r#"
-            url = "https://example.com"
-            bearer_token = "secret"
-        "#,
-    )
-    .expect_err("should reject bearer_token field");
-
-    assert!(
-        err.to_string().contains("bearer_token is not supported"),
-        "unexpected error: {err}"
-    );
-}

codex-rs/core/src/connectors.rs

@@ -27,6 +27,7 @@ use tracing::warn;
 use crate::AuthManager;
 use crate::CodexAuth;
 use crate::SandboxState;
+use crate::codex::INITIAL_SUBMIT_ID;
 use crate::config::Config;
 use crate::config::types::AppToolApproval;
 use crate::config::types::AppsConfigToml;
@@ -189,7 +190,8 @@ pub async fn list_accessible_connectors_from_mcp_tools_with_options_and_status(
         });
     }
     let cache_key = accessible_connectors_cache_key(config, auth.as_ref());
-    let mcp_manager = McpManager::new(Arc::new(PluginsManager::new(config.codex_home.clone())));
+    let plugins_manager = Arc::new(PluginsManager::new(config.codex_home.clone()));
+    let mcp_manager = McpManager::new(Arc::clone(&plugins_manager));
     let tool_plugin_provenance = mcp_manager.tool_plugin_provenance(config);
     if !force_refetch && let Some(cached_connectors) = read_cached_accessible_connectors(&cache_key)
     {
@@ -201,12 +203,8 @@ pub async fn list_accessible_connectors_from_mcp_tools_with_options_and_status(
         });
     }
 
-    let mcp_servers = with_codex_apps_mcp(
-        HashMap::new(),
-        /*connectors_enabled*/ true,
-        auth.as_ref(),
-        config,
-    );
+    let mcp_config = config.to_mcp_config(plugins_manager.as_ref());
+    let mcp_servers = with_codex_apps_mcp(HashMap::new(), auth.as_ref(), &mcp_config);
     if mcp_servers.is_empty() {
         return Ok(AccessibleConnectorsStatus {
             connectors: Vec::new(),
@@ -232,6 +230,7 @@ pub async fn list_accessible_connectors_from_mcp_tools_with_options_and_status(
         config.mcp_oauth_credentials_store_mode,
         auth_status_entries,
         &config.permissions.approval_policy,
+        INITIAL_SUBMIT_ID.to_owned(),
         tx_event,
         sandbox_state,
         config.codex_home.clone(),
@@ -717,10 +716,6 @@ pub fn filter_disallowed_connectors(connectors: Vec<AppInfo>) -> Vec<AppInfo> {
     filter_disallowed_connectors_for_originator(connectors, originator().value.as_str())
 }
 
-pub(crate) fn is_connector_id_allowed(connector_id: &str) -> bool {
-    is_connector_id_allowed_for_originator(connector_id, originator().value.as_str())
-}
-
 fn filter_disallowed_connectors_for_originator(
     connectors: Vec<AppInfo>,
     originator_value: &str,

codex-rs/core/src/lib.rs

@@ -46,15 +46,16 @@ mod hook_runtime;
 pub mod instructions;
 pub mod landlock;
 pub mod mcp;
-mod mcp_connection_manager;
+mod mcp_skill_dependencies;
 mod mcp_tool_approval_templates;
 pub mod models_manager;
 mod network_policy_decision;
 pub mod network_proxy_loader;
 mod original_image_detail;
-pub use mcp_connection_manager::MCP_SANDBOX_STATE_CAPABILITY;
-pub use mcp_connection_manager::MCP_SANDBOX_STATE_METHOD;
-pub use mcp_connection_manager::SandboxState;
+pub use codex_mcp::mcp_connection_manager;
+pub use codex_mcp::mcp_connection_manager::MCP_SANDBOX_STATE_CAPABILITY;
+pub use codex_mcp::mcp_connection_manager::MCP_SANDBOX_STATE_METHOD;
+pub use codex_mcp::mcp_connection_manager::SandboxState;
 pub use text_encoding::bytes_to_string_smart;
 mod mcp_tool_call;
 mod memories;
@@ -94,7 +95,6 @@ pub(crate) use skills::injection;
 pub(crate) use skills::loader;
 pub(crate) use skills::manager;
 pub(crate) use skills::maybe_emit_implicit_skill_invocation;
-pub(crate) use skills::model;
 pub(crate) use skills::render_skills_section;
 pub(crate) use skills::resolve_skill_dependencies_for_turn;
 pub(crate) use skills::skills_load_input_from_config;

codex-rs/core/src/mcp.rs

@@ -0,0 +1,53 @@
+use std::collections::HashMap;
+use std::sync::Arc;
+
+pub use codex_mcp::mcp::CODEX_APPS_MCP_SERVER_NAME;
+pub use codex_mcp::mcp::McpConfig;
+pub use codex_mcp::mcp::ToolPluginProvenance;
+pub use codex_mcp::mcp::auth;
+pub use codex_mcp::mcp::canonical_mcp_server_key;
+pub use codex_mcp::mcp::collect_mcp_snapshot;
+pub use codex_mcp::mcp::collect_mcp_snapshot_from_manager;
+pub use codex_mcp::mcp::collect_missing_mcp_dependencies;
+pub use codex_mcp::mcp::configured_mcp_servers;
+pub use codex_mcp::mcp::effective_mcp_servers;
+pub use codex_mcp::mcp::group_tools_by_server;
+pub use codex_mcp::mcp::qualified_mcp_tool_name_prefix;
+pub use codex_mcp::mcp::split_qualified_tool_name;
+pub use codex_mcp::mcp::tool_plugin_provenance as mcp_tool_plugin_provenance;
+pub use codex_mcp::mcp::with_codex_apps_mcp;
+
+use crate::CodexAuth;
+use crate::config::Config;
+use crate::plugins::PluginsManager;
+use codex_config::McpServerConfig;
+
+#[derive(Clone)]
+pub struct McpManager {
+    plugins_manager: Arc<PluginsManager>,
+}
+
+impl McpManager {
+    pub fn new(plugins_manager: Arc<PluginsManager>) -> Self {
+        Self { plugins_manager }
+    }
+
+    pub fn configured_servers(&self, config: &Config) -> HashMap<String, McpServerConfig> {
+        let mcp_config = config.to_mcp_config(self.plugins_manager.as_ref());
+        configured_mcp_servers(&mcp_config)
+    }
+
+    pub fn effective_servers(
+        &self,
+        config: &Config,
+        auth: Option<&CodexAuth>,
+    ) -> HashMap<String, McpServerConfig> {
+        let mcp_config = config.to_mcp_config(self.plugins_manager.as_ref());
+        effective_mcp_servers(&mcp_config, auth)
+    }
+
+    pub fn tool_plugin_provenance(&self, config: &Config) -> ToolPluginProvenance {
+        let mcp_config = config.to_mcp_config(self.plugins_manager.as_ref());
+        mcp_tool_plugin_provenance(&mcp_config)
+    }
+}

codex-rs/core/src/mcp_skill_dependencies.rs

@@ -1,6 +1,12 @@
 use std::collections::HashMap;
 use std::collections::HashSet;
 
+use codex_config::ConfigEditsBuilder;
+use codex_config::McpServerConfig;
+use codex_config::McpServerTransportConfig;
+use codex_config::load_global_mcp_servers;
+use codex_login::default_client::is_first_party_originator;
+use codex_login::default_client::originator;
 use codex_protocol::protocol::AskForApproval;
 use codex_protocol::protocol::SandboxPolicy;
 use codex_protocol::request_user_input::RequestUserInputArgs;
@@ -11,128 +17,19 @@ use codex_rmcp_client::perform_oauth_login;
 use tokio_util::sync::CancellationToken;
 use tracing::warn;
 
-use super::auth::McpOAuthLoginSupport;
-use super::auth::oauth_login_support;
-use super::auth::resolve_oauth_scopes;
-use super::auth::should_retry_without_scopes;
 use crate::SkillMetadata;
 use crate::codex::Session;
 use crate::codex::TurnContext;
-use crate::config::Config;
-use crate::config::edit::ConfigEditsBuilder;
-use crate::config::load_global_mcp_servers;
-use crate::config::types::McpServerConfig;
-use crate::config::types::McpServerTransportConfig;
-use crate::default_client::is_first_party_originator;
-use crate::default_client::originator;
-use crate::model::SkillToolDependency;
-use codex_features::Feature;
+use crate::mcp::auth::McpOAuthLoginSupport;
+use crate::mcp::auth::oauth_login_support;
+use crate::mcp::auth::resolve_oauth_scopes;
+use crate::mcp::auth::should_retry_without_scopes;
+use crate::skills::model::SkillToolDependency;
 
 const SKILL_MCP_DEPENDENCY_PROMPT_ID: &str = "skill_mcp_dependency_install";
 const MCP_DEPENDENCY_OPTION_INSTALL: &str = "Install";
 const MCP_DEPENDENCY_OPTION_SKIP: &str = "Continue anyway";
 
-fn is_full_access_mode(turn_context: &TurnContext) -> bool {
-    matches!(turn_context.approval_policy.value(), AskForApproval::Never)
-        && matches!(
-            turn_context.sandbox_policy.get(),
-            SandboxPolicy::DangerFullAccess | SandboxPolicy::ExternalSandbox { .. }
-        )
-}
-
-fn format_missing_mcp_dependencies(missing: &HashMap<String, McpServerConfig>) -> String {
-    let mut names = missing.keys().cloned().collect::<Vec<_>>();
-    names.sort();
-    names.join(", ")
-}
-
-async fn filter_prompted_mcp_dependencies(
-    sess: &Session,
-    missing: &HashMap<String, McpServerConfig>,
-) -> HashMap<String, McpServerConfig> {
-    let prompted = sess.mcp_dependency_prompted().await;
-    if prompted.is_empty() {
-        return missing.clone();
-    }
-
-    missing
-        .iter()
-        .filter(|(name, config)| !prompted.contains(&canonical_mcp_server_key(name, config)))
-        .map(|(name, config)| (name.clone(), config.clone()))
-        .collect()
-}
-
-async fn should_install_mcp_dependencies(
-    sess: &Session,
-    turn_context: &TurnContext,
-    missing: &HashMap<String, McpServerConfig>,
-    cancellation_token: &CancellationToken,
-) -> bool {
-    if is_full_access_mode(turn_context) {
-        return true;
-    }
-
-    let server_list = format_missing_mcp_dependencies(missing);
-    let question = RequestUserInputQuestion {
-        id: SKILL_MCP_DEPENDENCY_PROMPT_ID.to_string(),
-        header: "Install MCP servers?".to_string(),
-        question: format!(
-            "The following MCP servers are required by the selected skills but are not installed yet: {server_list}. Install them now?"
-        ),
-        is_other: false,
-        is_secret: false,
-        options: Some(vec![
-            RequestUserInputQuestionOption {
-                label: MCP_DEPENDENCY_OPTION_INSTALL.to_string(),
-                description:
-                    "Install and enable the missing MCP servers in your global config."
-                        .to_string(),
-            },
-            RequestUserInputQuestionOption {
-                label: MCP_DEPENDENCY_OPTION_SKIP.to_string(),
-                description: "Skip installation for now and do not show again for these MCP servers in this session."
-                    .to_string(),
-            },
-        ]),
-    };
-    let args = RequestUserInputArgs {
-        questions: vec![question],
-    };
-    let sub_id = &turn_context.sub_id;
-    let call_id = format!("mcp-deps-{sub_id}");
-    let response_fut = sess.request_user_input(turn_context, call_id, args);
-    let response = tokio::select! {
-        biased;
-        _ = cancellation_token.cancelled() => {
-            let empty = RequestUserInputResponse {
-                answers: HashMap::new(),
-            };
-            sess.notify_user_input_response(sub_id, empty.clone()).await;
-            empty
-        }
-        response = response_fut => response.unwrap_or_else(|| RequestUserInputResponse {
-            answers: HashMap::new(),
-        }),
-    };
-
-    let install = response
-        .answers
-        .get(SKILL_MCP_DEPENDENCY_PROMPT_ID)
-        .is_some_and(|answer| {
-            answer
-                .answers
-                .iter()
-                .any(|entry| entry == MCP_DEPENDENCY_OPTION_INSTALL)
-        });
-
-    let prompted_keys = missing
-        .iter()
-        .map(|(name, config)| canonical_mcp_server_key(name, config));
-    sess.record_mcp_dependency_prompted(prompted_keys).await;
-
-    install
-}
-
 pub(crate) async fn maybe_prompt_and_install_mcp_dependencies(
     sess: &Session,
     turn_context: &TurnContext,
@@ -146,7 +43,11 @@ pub(crate) async fn maybe_prompt_and_install_mcp_dependencies(
     }
 
     let config = turn_context.config.clone();
-    if mentioned_skills.is_empty() || !config.features.enabled(Feature::SkillMcpDependencyInstall) {
+    if mentioned_skills.is_empty()
+        || !config
+            .features
+            .enabled(codex_features::Feature::SkillMcpDependencyInstall)
+    {
         return;
     }
 
@@ -174,10 +75,14 @@ pub(crate) async fn maybe_prompt_and_install_mcp_dependencies(
 pub(crate) async fn maybe_install_mcp_dependencies(
     sess: &Session,
     turn_context: &TurnContext,
-    config: &Config,
+    config: &crate::config::Config,
     mentioned_skills: &[SkillMetadata],
 ) {
-    if mentioned_skills.is_empty() || !config.features.enabled(Feature::SkillMcpDependencyInstall) {
+    if mentioned_skills.is_empty()
+        || !config
+            .features
+            .enabled(codex_features::Feature::SkillMcpDependencyInstall)
+    {
         return;
     }
 
@@ -307,6 +212,107 @@ pub(crate) async fn maybe_install_mcp_dependencies(
     .await;
 }
 
+async fn should_install_mcp_dependencies(
+    sess: &Session,
+    turn_context: &TurnContext,
+    missing: &HashMap<String, McpServerConfig>,
+    cancellation_token: &CancellationToken,
+) -> bool {
+    if is_full_access_mode(turn_context) {
+        return true;
+    }
+
+    let server_list = format_missing_mcp_dependencies(missing);
+    let question = RequestUserInputQuestion {
+        id: SKILL_MCP_DEPENDENCY_PROMPT_ID.to_string(),
+        header: "Install MCP servers?".to_string(),
+        question: format!(
+            "The following MCP servers are required by the selected skills but are not installed yet: {server_list}. Install them now?"
+        ),
+        is_other: false,
+        is_secret: false,
+        options: Some(vec![
+            RequestUserInputQuestionOption {
+                label: MCP_DEPENDENCY_OPTION_INSTALL.to_string(),
+                description:
+                    "Install and enable the missing MCP servers in your global config."
+                        .to_string(),
+            },
+            RequestUserInputQuestionOption {
+                label: MCP_DEPENDENCY_OPTION_SKIP.to_string(),
+                description: "Skip installation for now and do not show again for these MCP servers in this session."
+                    .to_string(),
+            },
+        ]),
+    };
+    let args = RequestUserInputArgs {
+        questions: vec![question],
+    };
+    let sub_id = &turn_context.sub_id;
+    let call_id = format!("mcp-deps-{sub_id}");
+    let response_fut = sess.request_user_input(turn_context, call_id, args);
+    let response = tokio::select! {
+        biased;
+        _ = cancellation_token.cancelled() => {
+            let empty = RequestUserInputResponse {
+                answers: HashMap::new(),
+            };
+            sess.notify_user_input_response(sub_id, empty.clone()).await;
+            empty
+        }
+        response = response_fut => response.unwrap_or_else(|| RequestUserInputResponse {
+            answers: HashMap::new(),
+        }),
+    };
+
+    let install = response
+        .answers
+        .get(SKILL_MCP_DEPENDENCY_PROMPT_ID)
+        .is_some_and(|answer| {
+            answer
+                .answers
+                .iter()
+                .any(|entry| entry == MCP_DEPENDENCY_OPTION_INSTALL)
+        });
+
+    let prompted_keys = missing
+        .iter()
+        .map(|(name, config)| canonical_mcp_server_key(name, config));
+    sess.record_mcp_dependency_prompted(prompted_keys).await;
+
+    install
+}
+
+async fn filter_prompted_mcp_dependencies(
+    sess: &Session,
+    missing: &HashMap<String, McpServerConfig>,
+) -> HashMap<String, McpServerConfig> {
+    let prompted = sess.mcp_dependency_prompted().await;
+    if prompted.is_empty() {
+        return missing.clone();
+    }
+
+    missing
+        .iter()
+        .filter(|(name, config)| !prompted.contains(&canonical_mcp_server_key(name, config)))
+        .map(|(name, config)| (name.clone(), config.clone()))
+        .collect()
+}
+
+fn format_missing_mcp_dependencies(missing: &HashMap<String, McpServerConfig>) -> String {
+    let mut names = missing.keys().cloned().collect::<Vec<_>>();
+    names.sort();
+    names.join(", ")
+}
+
+fn is_full_access_mode(turn_context: &TurnContext) -> bool {
+    matches!(turn_context.approval_policy.value(), AskForApproval::Never)
+        && matches!(
+            turn_context.sandbox_policy.get(),
+            SandboxPolicy::DangerFullAccess | SandboxPolicy::ExternalSandbox { .. }
+        )
+}
+
 fn canonical_mcp_key(transport: &str, identifier: &str, fallback: &str) -> String {
     let identifier = identifier.trim();
     if identifier.is_empty() {
@@ -346,63 +352,6 @@ fn canonical_mcp_dependency_key(dependency: &SkillToolDependency) -> Result<Stri
     Err(format!("unsupported transport {transport}"))
 }
 
-pub(crate) fn collect_missing_mcp_dependencies(
-    mentioned_skills: &[SkillMetadata],
-    installed: &HashMap<String, McpServerConfig>,
-) -> HashMap<String, McpServerConfig> {
-    let mut missing = HashMap::new();
-    let installed_keys: HashSet<String> = installed
-        .iter()
-        .map(|(name, config)| canonical_mcp_server_key(name, config))
-        .collect();
-    let mut seen_canonical_keys = HashSet::new();
-
-    for skill in mentioned_skills {
-        let Some(dependencies) = skill.dependencies.as_ref() else {
-            continue;
-        };
-
-        for tool in &dependencies.tools {
-            if !tool.r#type.eq_ignore_ascii_case("mcp") {
-                continue;
-            }
-            let dependency_key = match canonical_mcp_dependency_key(tool) {
-                Ok(key) => key,
-                Err(err) => {
-                    let dependency = tool.value.as_str();
-                    let skill_name = skill.name.as_str();
-                    warn!(
-                        "unable to auto-install MCP dependency {dependency} for skill {skill_name}: {err}",
-                    );
-                    continue;
-                }
-            };
-            if installed_keys.contains(&dependency_key)
-                || seen_canonical_keys.contains(&dependency_key)
-            {
-                continue;
-            }
-
-            let config = match mcp_dependency_to_server_config(tool) {
-                Ok(config) => config,
-                Err(err) => {
-                    let dependency = dependency_key.as_str();
-                    let skill_name = skill.name.as_str();
-                    warn!(
-                        "unable to auto-install MCP dependency {dependency} for skill {skill_name}: {err}",
-                    );
-                    continue;
-                }
-            };
-
-            missing.insert(tool.value.clone(), config);
-            seen_canonical_keys.insert(dependency_key);
-        }
-    }
-
-    missing
-}
-
 fn mcp_dependency_to_server_config(
     dependency: &SkillToolDependency,
 ) -> Result<McpServerConfig, String> {
@@ -461,6 +410,59 @@ fn mcp_dependency_to_server_config(
     Err(format!("unsupported transport {transport}"))
 }
 
-#[cfg(test)]
-#[path = "skill_dependencies_tests.rs"]
-mod tests;
+fn collect_missing_mcp_dependencies(
+    mentioned_skills: &[SkillMetadata],
+    installed: &HashMap<String, McpServerConfig>,
+) -> HashMap<String, McpServerConfig> {
+    let mut missing = HashMap::new();
+    let installed_keys: HashSet<String> = installed
+        .iter()
+        .map(|(name, config)| canonical_mcp_server_key(name, config))
+        .collect();
+    let mut seen_canonical_keys = HashSet::new();
+
+    for skill in mentioned_skills {
+        let Some(dependencies) = skill.dependencies.as_ref() else {
+            continue;
+        };
+
+        for tool in &dependencies.tools {
+            if !tool.r#type.eq_ignore_ascii_case("mcp") {
+                continue;
+            }
+            let dependency_key = match canonical_mcp_dependency_key(tool) {
+                Ok(key) => key,
+                Err(err) => {
+                    let dependency = tool.value.as_str();
+                    let skill_name = skill.name.as_str();
+                    warn!(
+                        "unable to auto-install MCP dependency {dependency} for skill {skill_name}: {err}",
+                    );
+                    continue;
+                }
+            };
+            if installed_keys.contains(&dependency_key)
+                || seen_canonical_keys.contains(&dependency_key)
+            {
+                continue;
+            }
+
+            let config = match mcp_dependency_to_server_config(tool) {
+                Ok(config) => config,
+                Err(err) => {
+                    let dependency = dependency_key.as_str();
+                    let skill_name = skill.name.as_str();
+                    warn!(
+                        "unable to auto-install MCP dependency {dependency} for skill {skill_name}: {err}",
+                    );
+                    continue;
+                }
+            };
+
+            missing.insert(tool.value.clone(), config);
+            seen_canonical_keys.insert(dependency_key);
+        }
+    }
+
+    missing
+}

codex-rs/utils/plugins/Cargo.toml

@@ -14,6 +14,7 @@ path = "src/lib.rs"
 workspace = true
 
 [dependencies]
+codex-login = { workspace = true }
 serde = { workspace = true, features = ["derive"] }
 serde_json = { workspace = true }
 

codex-rs/utils/plugins/src/lib.rs

@@ -1,5 +1,7 @@
-//! Plugin path resolution and plaintext mention sigils shared across Codex crates.
+//! Plugin path resolution, plaintext mention sigils, and MCP connector helpers shared across Codex
+//! crates.
 
+pub mod mcp_connector;
 pub mod mention_syntax;
 pub mod plugin_namespace;
 

codex-rs/utils/plugins/src/mcp_connector.rs

@@ -0,0 +1,50 @@
+use codex_login::default_client::is_first_party_chat_originator;
+use codex_login::default_client::originator;
+
+const DISALLOWED_CONNECTOR_IDS: &[&str] = &[
+    "asdk_app_6938a94a61d881918ef32cb999ff937c",
+    "connector_2b0a9009c9c64bf9933a3dae3f2b1254",
+    "connector_3f8d1a79f27c4c7ba1a897ab13bf37dc",
+    "connector_68de829bf7648191acd70a907364c67c",
+    "connector_68e004f14af881919eb50893d3d9f523",
+    "connector_69272cb413a081919685ec3c88d1744e",
+];
+const FIRST_PARTY_CHAT_DISALLOWED_CONNECTOR_IDS: &[&str] =
+    &["connector_0f9c9d4592e54d0a9a12b3f44a1e2010"];
+const DISALLOWED_CONNECTOR_PREFIX: &str = "connector_openai_";
+
+pub fn is_connector_id_allowed(connector_id: &str) -> bool {
+    is_connector_id_allowed_for_originator(connector_id, originator().value.as_str())
+}
+
+fn is_connector_id_allowed_for_originator(connector_id: &str, originator_value: &str) -> bool {
+    let disallowed_connector_ids = if is_first_party_chat_originator(originator_value) {
+        FIRST_PARTY_CHAT_DISALLOWED_CONNECTOR_IDS
+    } else {
+        DISALLOWED_CONNECTOR_IDS
+    };
+
+    !connector_id.starts_with(DISALLOWED_CONNECTOR_PREFIX)
+        && !disallowed_connector_ids.contains(&connector_id)
+}
+
+pub fn sanitize_name(name: &str) -> String {
+    sanitize_slug(name).replace("-", "_")
+}
+
+fn sanitize_slug(name: &str) -> String {
+    let mut normalized = String::with_capacity(name.len());
+    for character in name.chars() {
+        if character.is_ascii_alphanumeric() {
+            normalized.push(character.to_ascii_lowercase());
+        } else {
+            normalized.push('-');
+        }
+    }
+    let normalized = normalized.trim_matches('-');
+    if normalized.is_empty() {
+        "app".to_string()
+    } else {
+        normalized.to_string()
+    }
+}