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/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

@@ -0,0 +1,299 @@
+use std::collections::HashMap;
+
+use anyhow::Result;
+use codex_protocol::protocol::McpAuthStatus;
+use codex_rmcp_client::OAuthCredentialsStoreMode;
+use codex_rmcp_client::OAuthProviderError;
+use codex_rmcp_client::determine_streamable_http_auth_status;
+use codex_rmcp_client::discover_streamable_http_oauth;
+use futures::future::join_all;
+use tracing::warn;
+
+use codex_config::McpServerConfig;
+use codex_config::McpServerTransportConfig;
+
+#[derive(Debug, Clone)]
+pub struct McpOAuthLoginConfig {
+    pub url: String,
+    pub http_headers: Option<HashMap<String, String>>,
+    pub env_http_headers: Option<HashMap<String, String>>,
+    pub discovered_scopes: Option<Vec<String>>,
+}
+
+#[derive(Debug)]
+pub enum McpOAuthLoginSupport {
+    Supported(McpOAuthLoginConfig),
+    Unsupported,
+    Unknown(anyhow::Error),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum McpOAuthScopesSource {
+    Explicit,
+    Configured,
+    Discovered,
+    Empty,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ResolvedMcpOAuthScopes {
+    pub scopes: Vec<String>,
+    pub source: McpOAuthScopesSource,
+}
+
+pub async fn oauth_login_support(transport: &McpServerTransportConfig) -> McpOAuthLoginSupport {
+    let McpServerTransportConfig::StreamableHttp {
+        url,
+        bearer_token_env_var,
+        http_headers,
+        env_http_headers,
+    } = transport
+    else {
+        return McpOAuthLoginSupport::Unsupported;
+    };
+
+    if bearer_token_env_var.is_some() {
+        return McpOAuthLoginSupport::Unsupported;
+    }
+
+    match discover_streamable_http_oauth(url, http_headers.clone(), env_http_headers.clone()).await
+    {
+        Ok(Some(discovery)) => McpOAuthLoginSupport::Supported(McpOAuthLoginConfig {
+            url: url.clone(),
+            http_headers: http_headers.clone(),
+            env_http_headers: env_http_headers.clone(),
+            discovered_scopes: discovery.scopes_supported,
+        }),
+        Ok(None) => McpOAuthLoginSupport::Unsupported,
+        Err(err) => McpOAuthLoginSupport::Unknown(err),
+    }
+}
+
+pub async fn discover_supported_scopes(
+    transport: &McpServerTransportConfig,
+) -> Option<Vec<String>> {
+    match oauth_login_support(transport).await {
+        McpOAuthLoginSupport::Supported(config) => config.discovered_scopes,
+        McpOAuthLoginSupport::Unsupported | McpOAuthLoginSupport::Unknown(_) => None,
+    }
+}
+
+pub fn resolve_oauth_scopes(
+    explicit_scopes: Option<Vec<String>>,
+    configured_scopes: Option<Vec<String>>,
+    discovered_scopes: Option<Vec<String>>,
+) -> ResolvedMcpOAuthScopes {
+    if let Some(scopes) = explicit_scopes {
+        return ResolvedMcpOAuthScopes {
+            scopes,
+            source: McpOAuthScopesSource::Explicit,
+        };
+    }
+
+    if let Some(scopes) = configured_scopes {
+        return ResolvedMcpOAuthScopes {
+            scopes,
+            source: McpOAuthScopesSource::Configured,
+        };
+    }
+
+    if let Some(scopes) = discovered_scopes
+        && !scopes.is_empty()
+    {
+        return ResolvedMcpOAuthScopes {
+            scopes,
+            source: McpOAuthScopesSource::Discovered,
+        };
+    }
+
+    ResolvedMcpOAuthScopes {
+        scopes: Vec::new(),
+        source: McpOAuthScopesSource::Empty,
+    }
+}
+
+pub fn should_retry_without_scopes(scopes: &ResolvedMcpOAuthScopes, error: &anyhow::Error) -> bool {
+    scopes.source == McpOAuthScopesSource::Discovered
+        && error.downcast_ref::<OAuthProviderError>().is_some()
+}
+
+#[derive(Debug, Clone)]
+pub struct McpAuthStatusEntry {
+    pub config: McpServerConfig,
+    pub auth_status: McpAuthStatus,
+}
+
+pub async fn compute_auth_statuses<'a, I>(
+    servers: I,
+    store_mode: OAuthCredentialsStoreMode,
+) -> HashMap<String, McpAuthStatusEntry>
+where
+    I: IntoIterator<Item = (&'a String, &'a McpServerConfig)>,
+{
+    let futures = servers.into_iter().map(|(name, config)| {
+        let name = name.clone();
+        let config = config.clone();
+        async move {
+            let auth_status = match compute_auth_status(&name, &config, store_mode).await {
+                Ok(status) => status,
+                Err(error) => {
+                    warn!("failed to determine auth status for MCP server `{name}`: {error:?}");
+                    McpAuthStatus::Unsupported
+                }
+            };
+            let entry = McpAuthStatusEntry {
+                config,
+                auth_status,
+            };
+            (name, entry)
+        }
+    });
+
+    join_all(futures).await.into_iter().collect()
+}
+
+async fn compute_auth_status(
+    server_name: &str,
+    config: &McpServerConfig,
+    store_mode: OAuthCredentialsStoreMode,
+) -> Result<McpAuthStatus> {
+    match &config.transport {
+        McpServerTransportConfig::Stdio { .. } => Ok(McpAuthStatus::Unsupported),
+        McpServerTransportConfig::StreamableHttp {
+            url,
+            bearer_token_env_var,
+            http_headers,
+            env_http_headers,
+        } => {
+            determine_streamable_http_auth_status(
+                server_name,
+                url,
+                bearer_token_env_var.as_deref(),
+                http_headers.clone(),
+                env_http_headers.clone(),
+                store_mode,
+            )
+            .await
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use anyhow::anyhow;
+    use pretty_assertions::assert_eq;
+
+    use super::McpOAuthScopesSource;
+    use super::OAuthProviderError;
+    use super::ResolvedMcpOAuthScopes;
+    use super::resolve_oauth_scopes;
+    use super::should_retry_without_scopes;
+
+    #[test]
+    fn resolve_oauth_scopes_prefers_explicit() {
+        let resolved = resolve_oauth_scopes(
+            Some(vec!["explicit".to_string()]),
+            Some(vec!["configured".to_string()]),
+            Some(vec!["discovered".to_string()]),
+        );
+
+        assert_eq!(
+            resolved,
+            ResolvedMcpOAuthScopes {
+                scopes: vec!["explicit".to_string()],
+                source: McpOAuthScopesSource::Explicit,
+            }
+        );
+    }
+
+    #[test]
+    fn resolve_oauth_scopes_prefers_configured_over_discovered() {
+        let resolved = resolve_oauth_scopes(
+            /*explicit_scopes*/ None,
+            Some(vec!["configured".to_string()]),
+            Some(vec!["discovered".to_string()]),
+        );
+
+        assert_eq!(
+            resolved,
+            ResolvedMcpOAuthScopes {
+                scopes: vec!["configured".to_string()],
+                source: McpOAuthScopesSource::Configured,
+            }
+        );
+    }
+
+    #[test]
+    fn resolve_oauth_scopes_uses_discovered_when_needed() {
+        let resolved = resolve_oauth_scopes(
+            /*explicit_scopes*/ None,
+            /*configured_scopes*/ None,
+            Some(vec!["discovered".to_string()]),
+        );
+
+        assert_eq!(
+            resolved,
+            ResolvedMcpOAuthScopes {
+                scopes: vec!["discovered".to_string()],
+                source: McpOAuthScopesSource::Discovered,
+            }
+        );
+    }
+
+    #[test]
+    fn resolve_oauth_scopes_preserves_explicitly_empty_configured_scopes() {
+        let resolved = resolve_oauth_scopes(
+            /*explicit_scopes*/ None,
+            Some(Vec::new()),
+            Some(vec!["ignored".into()]),
+        );
+
+        assert_eq!(
+            resolved,
+            ResolvedMcpOAuthScopes {
+                scopes: Vec::new(),
+                source: McpOAuthScopesSource::Configured,
+            }
+        );
+    }
+
+    #[test]
+    fn resolve_oauth_scopes_falls_back_to_empty() {
+        let resolved = resolve_oauth_scopes(
+            /*explicit_scopes*/ None, /*configured_scopes*/ None,
+            /*discovered_scopes*/ None,
+        );
+
+        assert_eq!(
+            resolved,
+            ResolvedMcpOAuthScopes {
+                scopes: Vec::new(),
+                source: McpOAuthScopesSource::Empty,
+            }
+        );
+    }
+
+    #[test]
+    fn should_retry_without_scopes_only_for_discovered_provider_errors() {
+        let discovered = ResolvedMcpOAuthScopes {
+            scopes: vec!["scope".to_string()],
+            source: McpOAuthScopesSource::Discovered,
+        };
+        let provider_error = anyhow!(OAuthProviderError::new(
+            Some("invalid_scope".to_string()),
+            Some("scope rejected".to_string()),
+        ));
+
+        assert!(should_retry_without_scopes(&discovered, &provider_error));
+
+        let configured = ResolvedMcpOAuthScopes {
+            scopes: vec!["scope".to_string()],
+            source: McpOAuthScopesSource::Configured,
+        };
+        assert!(!should_retry_without_scopes(&configured, &provider_error));
+        assert!(!should_retry_without_scopes(
+            &discovered,
+            &anyhow!("timed out waiting for OAuth callback"),
+        ));
+    }
+}

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

@@ -0,0 +1,476 @@
+pub mod auth;
+mod skill_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::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::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;
+pub type McpManager = McpConnectionManager;
+
+const MCP_TOOL_NAME_PREFIX: &str = "mcp";
+const MCP_TOOL_NAME_DELIMITER: &str = "__";
+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_-]+$`.
+/// MCP server/tool names are user-controlled, so sanitize the fully-qualified
+/// name we expose to the model by replacing any disallowed character with `_`.
+pub(crate) fn sanitize_responses_api_tool_name(name: &str) -> String {
+    let mut sanitized = String::with_capacity(name.len());
+    for c in name.chars() {
+        if c.is_ascii_alphanumeric() || c == '_' {
+            sanitized.push(c);
+        } else {
+            sanitized.push('_');
+        }
+    }
+
+    if sanitized.is_empty() {
+        "_".to_string()
+    } else {
+        sanitized
+    }
+}
+
+pub fn qualified_mcp_tool_name_prefix(server_name: &str) -> String {
+    sanitize_responses_api_tool_name(&format!(
+        "{MCP_TOOL_NAME_PREFIX}{MCP_TOOL_NAME_DELIMITER}{server_name}{MCP_TOOL_NAME_DELIMITER}"
+    ))
+}
+
+/// 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>>,
+    plugin_display_names_by_mcp_server_name: HashMap<String, Vec<String>>,
+}
+
+impl ToolPluginProvenance {
+    pub fn plugin_display_names_for_connector_id(&self, connector_id: &str) -> &[String] {
+        self.plugin_display_names_by_connector_id
+            .get(connector_id)
+            .map(Vec::as_slice)
+            .unwrap_or(&[])
+    }
+
+    pub fn plugin_display_names_for_mcp_server_name(&self, server_name: &str) -> &[String] {
+        self.plugin_display_names_by_mcp_server_name
+            .get(server_name)
+            .map(Vec::as_slice)
+            .unwrap_or(&[])
+    }
+
+    fn from_capability_summaries(capability_summaries: &[PluginCapabilitySummary]) -> Self {
+        let mut tool_plugin_provenance = Self::default();
+        for plugin in capability_summaries {
+            for connector_id in &plugin.app_connector_ids {
+                tool_plugin_provenance
+                    .plugin_display_names_by_connector_id
+                    .entry(connector_id.0.clone())
+                    .or_default()
+                    .push(plugin.display_name.clone());
+            }
+
+            for server_name in &plugin.mcp_server_names {
+                tool_plugin_provenance
+                    .plugin_display_names_by_mcp_server_name
+                    .entry(server_name.clone())
+                    .or_default()
+                    .push(plugin.display_name.clone());
+            }
+        }
+
+        for plugin_names in tool_plugin_provenance
+            .plugin_display_names_by_connector_id
+            .values_mut()
+            .chain(
+                tool_plugin_provenance
+                    .plugin_display_names_by_mcp_server_name
+                    .values_mut(),
+            )
+        {
+            plugin_names.sort_unstable();
+            plugin_names.dedup();
+        }
+
+        tool_plugin_provenance
+    }
+}
+
+fn codex_apps_mcp_bearer_token_env_var() -> Option<String> {
+    match env::var(CODEX_CONNECTORS_TOKEN_ENV_VAR) {
+        Ok(value) if !value.trim().is_empty() => Some(CODEX_CONNECTORS_TOKEN_ENV_VAR.to_string()),
+        Ok(_) => None,
+        Err(env::VarError::NotPresent) => None,
+        Err(env::VarError::NotUnicode(_)) => Some(CODEX_CONNECTORS_TOKEN_ENV_VAR.to_string()),
+    }
+}
+
+fn codex_apps_mcp_bearer_token(auth: Option<&CodexAuth>) -> Option<String> {
+    let token = auth.and_then(|auth| auth.get_token().ok())?;
+    let token = token.trim();
+    if token.is_empty() {
+        None
+    } else {
+        Some(token.to_string())
+    }
+}
+
+fn codex_apps_mcp_http_headers(auth: Option<&CodexAuth>) -> Option<HashMap<String, String>> {
+    let mut headers = HashMap::new();
+    if let Some(token) = codex_apps_mcp_bearer_token(auth) {
+        headers.insert("Authorization".to_string(), format!("Bearer {token}"));
+    }
+    if let Some(account_id) = auth.and_then(CodexAuth::get_account_id) {
+        headers.insert("ChatGPT-Account-ID".to_string(), account_id);
+    }
+    if headers.is_empty() {
+        None
+    } else {
+        Some(headers)
+    }
+}
+
+fn normalize_codex_apps_base_url(base_url: &str) -> String {
+    let mut base_url = base_url.trim_end_matches('/').to_string();
+    if (base_url.starts_with("https://chatgpt.com")
+        || base_url.starts_with("https://chat.openai.com"))
+        && !base_url.contains("/backend-api")
+    {
+        base_url = format!("{base_url}/backend-api");
+    }
+    base_url
+}
+
+fn codex_apps_mcp_url_for_base_url(base_url: &str) -> String {
+    let base_url = normalize_codex_apps_base_url(base_url);
+    if base_url.contains("/backend-api") {
+        format!("{base_url}/wham/apps")
+    } else if base_url.contains("/api/codex") {
+        format!("{base_url}/apps")
+    } else {
+        format!("{base_url}/api/codex/apps")
+    }
+}
+
+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: &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
+    } else {
+        codex_apps_mcp_http_headers(auth)
+    };
+    let url = codex_apps_mcp_url(config);
+
+    McpServerConfig {
+        transport: McpServerTransportConfig::StreamableHttp {
+            url,
+            bearer_token_env_var,
+            http_headers,
+            env_http_headers: None,
+        },
+        enabled: true,
+        required: false,
+        disabled_reason: None,
+        startup_timeout_sec: Some(Duration::from_secs(30)),
+        tool_timeout_sec: None,
+        enabled_tools: None,
+        disabled_tools: None,
+        scopes: None,
+        oauth_resource: None,
+        tools: HashMap::new(),
+    }
+}
+
+pub fn with_codex_apps_mcp(
+    mut servers: HashMap<String, McpServerConfig>,
+    auth: Option<&CodexAuth>,
+    config: &McpConfig,
+) -> HashMap<String, McpServerConfig> {
+    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),
+        );
+    } else {
+        servers.remove(CODEX_APPS_MCP_SERVER_NAME);
+    }
+    servers
+}
+
+pub fn configured_mcp_servers(config: &McpConfig) -> HashMap<String, McpServerConfig> {
+    config.configured_mcp_servers.clone()
+}
+
+pub fn effective_mcp_servers(
+    config: &McpConfig,
+    auth: Option<&CodexAuth>,
+) -> HashMap<String, McpServerConfig> {
+    let servers = configured_mcp_servers(config);
+    with_codex_apps_mcp(servers, auth, 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(),
+            resources: HashMap::new(),
+            resource_templates: HashMap::new(),
+            auth_statuses: HashMap::new(),
+        };
+    }
+
+    let auth_status_entries =
+        compute_auth_statuses(mcp_servers.iter(), config.mcp_oauth_credentials_store_mode).await;
+
+    let (tx_event, rx_event) = unbounded();
+    drop(rx_event);
+
+    // Use ReadOnly sandbox policy for MCP snapshot collection (safest default)
+    let sandbox_state = SandboxState {
+        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.use_legacy_landlock,
+    };
+
+    let (mcp_connection_manager, cancel_token) = McpConnectionManager::new(
+        &mcp_servers,
+        config.mcp_oauth_credentials_store_mode,
+        auth_status_entries.clone(),
+        &config.approval_policy,
+        submit_id,
+        tx_event,
+        sandbox_state,
+        config.codex_home.clone(),
+        codex_apps_tools_cache_key(auth),
+        tool_plugin_provenance,
+    )
+    .await;
+
+    let snapshot =
+        collect_mcp_snapshot_from_manager(&mcp_connection_manager, auth_status_entries).await;
+
+    cancel_token.cancel();
+
+    snapshot
+}
+
+pub fn split_qualified_tool_name(qualified_name: &str) -> Option<(String, String)> {
+    let mut parts = qualified_name.split(MCP_TOOL_NAME_DELIMITER);
+    let prefix = parts.next()?;
+    if prefix != MCP_TOOL_NAME_PREFIX {
+        return None;
+    }
+    let server_name = parts.next()?;
+    let tool_name: String = parts.collect::<Vec<_>>().join(MCP_TOOL_NAME_DELIMITER);
+    if tool_name.is_empty() {
+        return None;
+    }
+    Some((server_name.to_string(), tool_name))
+}
+
+pub fn group_tools_by_server(
+    tools: &HashMap<String, Tool>,
+) -> HashMap<String, HashMap<String, Tool>> {
+    let mut grouped = HashMap::new();
+    for (qualified_name, tool) in tools {
+        if let Some((server_name, tool_name)) = split_qualified_tool_name(qualified_name) {
+            grouped
+                .entry(server_name)
+                .or_insert_with(HashMap::new)
+                .insert(tool_name, tool.clone());
+        }
+    }
+    grouped
+}
+
+pub async fn collect_mcp_snapshot_from_manager(
+    mcp_connection_manager: &McpConnectionManager,
+    auth_status_entries: HashMap<String, crate::mcp::auth::McpAuthStatusEntry>,
+) -> McpListToolsResponseEvent {
+    let (tools, resources, resource_templates) = tokio::join!(
+        mcp_connection_manager.list_all_tools(),
+        mcp_connection_manager.list_all_resources(),
+        mcp_connection_manager.list_all_resource_templates(),
+    );
+
+    let auth_statuses = auth_status_entries
+        .iter()
+        .map(|(name, entry)| (name.clone(), entry.auth_status))
+        .collect::<HashMap<_, _>>();
+
+    let tools = tools
+        .into_iter()
+        .filter_map(|(name, tool)| match serde_json::to_value(tool.tool) {
+            Ok(value) => match Tool::from_mcp_value(value) {
+                Ok(tool) => Some((name, tool)),
+                Err(err) => {
+                    tracing::warn!("Failed to convert MCP tool '{name}': {err}");
+                    None
+                }
+            },
+            Err(err) => {
+                tracing::warn!("Failed to serialize MCP tool '{name}': {err}");
+                None
+            }
+        })
+        .collect::<HashMap<_, _>>();
+
+    let resources = resources
+        .into_iter()
+        .map(|(name, resources)| {
+            let resources = resources
+                .into_iter()
+                .filter_map(|resource| match serde_json::to_value(resource) {
+                    Ok(value) => match Resource::from_mcp_value(value.clone()) {
+                        Ok(resource) => Some(resource),
+                        Err(err) => {
+                            let (uri, resource_name) = match value {
+                                Value::Object(obj) => (
+                                    obj.get("uri")
+                                        .and_then(|v| v.as_str().map(ToString::to_string)),
+                                    obj.get("name")
+                                        .and_then(|v| v.as_str().map(ToString::to_string)),
+                                ),
+                                _ => (None, None),
+                            };
+
+                            tracing::warn!(
+                                "Failed to convert MCP resource (uri={uri:?}, name={resource_name:?}): {err}"
+                            );
+                            None
+                        }
+                    },
+                    Err(err) => {
+                        tracing::warn!("Failed to serialize MCP resource: {err}");
+                        None
+                    }
+                })
+                .collect::<Vec<_>>();
+            (name, resources)
+        })
+        .collect::<HashMap<_, _>>();
+
+    let resource_templates = resource_templates
+        .into_iter()
+        .map(|(name, templates)| {
+            let templates = templates
+                .into_iter()
+                .filter_map(|template| match serde_json::to_value(template) {
+                    Ok(value) => match ResourceTemplate::from_mcp_value(value.clone()) {
+                        Ok(template) => Some(template),
+                        Err(err) => {
+                            let (uri_template, template_name) = match value {
+                                Value::Object(obj) => (
+                                    obj.get("uriTemplate")
+                                        .or_else(|| obj.get("uri_template"))
+                                        .and_then(|v| v.as_str().map(ToString::to_string)),
+                                    obj.get("name")
+                                        .and_then(|v| v.as_str().map(ToString::to_string)),
+                                ),
+                                _ => (None, None),
+                            };
+
+                            tracing::warn!(
+                                "Failed to convert MCP resource template (uri_template={uri_template:?}, name={template_name:?}): {err}"
+                            );
+                            None
+                        }
+                    },
+                    Err(err) => {
+                        tracing::warn!("Failed to serialize MCP resource template: {err}");
+                        None
+                    }
+                })
+                .collect::<Vec<_>>();
+            (name, templates)
+        })
+        .collect::<HashMap<_, _>>();
+
+    McpListToolsResponseEvent {
+        tools,
+        resources,
+        resource_templates,
+        auth_statuses,
+    }
+}
+
+#[cfg(test)]
+#[path = "mod_tests.rs"]
+mod tests;

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

@@ -0,0 +1,258 @@
+use super::*;
+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::collections::HashMap;
+use std::path::PathBuf;
+
+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 {
+    Tool {
+        name: name.to_string(),
+        title: None,
+        description: None,
+        input_schema: serde_json::json!({"type": "object", "properties": {}}),
+        output_schema: None,
+        annotations: None,
+        icons: None,
+        meta: None,
+    }
+}
+
+#[test]
+fn split_qualified_tool_name_returns_server_and_tool() {
+    assert_eq!(
+        split_qualified_tool_name("mcp__alpha__do_thing"),
+        Some(("alpha".to_string(), "do_thing".to_string()))
+    );
+}
+
+#[test]
+fn qualified_mcp_tool_name_prefix_sanitizes_server_names_without_lowercasing() {
+    assert_eq!(
+        qualified_mcp_tool_name_prefix("Some-Server"),
+        "mcp__Some_Server__".to_string()
+    );
+}
+
+#[test]
+fn split_qualified_tool_name_rejects_invalid_names() {
+    assert_eq!(split_qualified_tool_name("other__alpha__do_thing"), None);
+    assert_eq!(split_qualified_tool_name("mcp__alpha__"), None);
+}
+
+#[test]
+fn group_tools_by_server_strips_prefix_and_groups() {
+    let mut tools = HashMap::new();
+    tools.insert("mcp__alpha__do_thing".to_string(), make_tool("do_thing"));
+    tools.insert(
+        "mcp__alpha__nested__op".to_string(),
+        make_tool("nested__op"),
+    );
+    tools.insert("mcp__beta__do_other".to_string(), make_tool("do_other"));
+
+    let mut expected_alpha = HashMap::new();
+    expected_alpha.insert("do_thing".to_string(), make_tool("do_thing"));
+    expected_alpha.insert("nested__op".to_string(), make_tool("nested__op"));
+
+    let mut expected_beta = HashMap::new();
+    expected_beta.insert("do_other".to_string(), make_tool("do_other"));
+
+    let mut expected = HashMap::new();
+    expected.insert("alpha".to_string(), expected_alpha);
+    expected.insert("beta".to_string(), expected_beta);
+
+    assert_eq!(group_tools_by_server(&tools), expected);
+}
+
+#[test]
+fn tool_plugin_provenance_collects_app_and_mcp_sources() {
+    let provenance = ToolPluginProvenance::from_capability_summaries(&[
+        PluginCapabilitySummary {
+            display_name: "alpha-plugin".to_string(),
+            app_connector_ids: vec![AppConnectorId("connector_example".to_string())],
+            mcp_server_names: vec!["alpha".to_string()],
+            ..PluginCapabilitySummary::default()
+        },
+        PluginCapabilitySummary {
+            display_name: "beta-plugin".to_string(),
+            app_connector_ids: vec![
+                AppConnectorId("connector_example".to_string()),
+                AppConnectorId("connector_gmail".to_string()),
+            ],
+            mcp_server_names: vec!["beta".to_string()],
+            ..PluginCapabilitySummary::default()
+        },
+    ]);
+
+    assert_eq!(
+        provenance,
+        ToolPluginProvenance {
+            plugin_display_names_by_connector_id: HashMap::from([
+                (
+                    "connector_example".to_string(),
+                    vec!["alpha-plugin".to_string(), "beta-plugin".to_string()],
+                ),
+                (
+                    "connector_gmail".to_string(),
+                    vec!["beta-plugin".to_string()],
+                ),
+            ]),
+            plugin_display_names_by_mcp_server_name: HashMap::from([
+                ("alpha".to_string(), vec!["alpha-plugin".to_string()]),
+                ("beta".to_string(), vec!["beta-plugin".to_string()]),
+            ]),
+        }
+    );
+}
+
+#[test]
+fn codex_apps_mcp_url_for_base_url_keeps_existing_paths() {
+    assert_eq!(
+        codex_apps_mcp_url_for_base_url("https://chatgpt.com/backend-api"),
+        "https://chatgpt.com/backend-api/wham/apps"
+    );
+    assert_eq!(
+        codex_apps_mcp_url_for_base_url("https://chat.openai.com"),
+        "https://chat.openai.com/backend-api/wham/apps"
+    );
+    assert_eq!(
+        codex_apps_mcp_url_for_base_url("http://localhost:8080/api/codex"),
+        "http://localhost:8080/api/codex/apps"
+    );
+    assert_eq!(
+        codex_apps_mcp_url_for_base_url("http://localhost:8080"),
+        "http://localhost:8080/api/codex/apps"
+    );
+}
+
+#[test]
+fn codex_apps_mcp_url_uses_legacy_codex_apps_path() {
+    let config = test_mcp_config(PathBuf::from("/tmp"));
+
+    assert_eq!(
+        codex_apps_mcp_url(&config),
+        "https://chatgpt.com/backend-api/wham/apps"
+    );
+}
+
+#[test]
+fn codex_apps_server_config_uses_legacy_codex_apps_path() {
+    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(), /*auth*/ None, &config);
+    assert!(!servers.contains_key(CODEX_APPS_MCP_SERVER_NAME));
+
+    config.apps_enabled = true;
+
+    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");
+    let url = match &server.transport {
+        McpServerTransportConfig::StreamableHttp { url, .. } => url,
+        _ => panic!("expected streamable http transport for codex apps"),
+    };
+
+    assert_eq!(url, "https://chatgpt.com/backend-api/wham/apps");
+}
+
+#[tokio::test]
+async fn effective_mcp_servers_preserve_user_servers_and_add_codex_apps() {
+    let codex_home = tempfile::tempdir().expect("tempdir");
+    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();
+
+    config.configured_mcp_servers.insert(
+        "sample".to_string(),
+        McpServerConfig {
+            transport: McpServerTransportConfig::StreamableHttp {
+                url: "https://user.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(),
+        },
+    );
+    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 effective = effective_mcp_servers(&config, Some(&auth));
+
+    let sample = effective.get("sample").expect("user 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, .. } => {
+            assert_eq!(url, "https://user.example/mcp");
+        }
+        other => panic!("expected streamable http transport, got {other:?}"),
+    }
+    match &docs.transport {
+        McpServerTransportConfig::StreamableHttp { url, .. } => {
+            assert_eq!(url, "https://docs.example/mcp");
+        }
+        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

@@ -0,0 +1,108 @@
+use super::*;
+use codex_protocol::protocol::SkillDependencies;
+use codex_protocol::protocol::SkillMetadata;
+use codex_protocol::protocol::SkillScope;
+use pretty_assertions::assert_eq;
+use std::path::PathBuf;
+
+fn skill_with_tools(tools: Vec<SkillToolDependency>) -> SkillMetadata {
+    SkillMetadata {
+        name: "skill".to_string(),
+        description: "skill".to_string(),
+        short_description: None,
+        interface: None,
+        dependencies: Some(SkillDependencies { tools }),
+        path: PathBuf::from("skill"),
+        scope: SkillScope::User,
+        enabled: true,
+    }
+}
+
+#[test]
+fn collect_missing_respects_canonical_installed_key() {
+    let url = "https://example.com/mcp".to_string();
+    let skills = vec![skill_with_tools(vec![SkillToolDependency {
+        r#type: "mcp".to_string(),
+        value: "github".to_string(),
+        description: None,
+        transport: Some("streamable_http".to_string()),
+        command: None,
+        url: Some(url.clone()),
+    }])];
+    let installed = HashMap::from([(
+        "alias".to_string(),
+        McpServerConfig {
+            transport: McpServerTransportConfig::StreamableHttp {
+                url,
+                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(),
+        },
+    )]);
+
+    assert_eq!(
+        collect_missing_mcp_dependencies(&skills, &installed),
+        HashMap::new()
+    );
+}
+
+#[test]
+fn collect_missing_dedupes_by_canonical_key_but_preserves_original_name() {
+    let url = "https://example.com/one".to_string();
+    let skills = vec![skill_with_tools(vec![
+        SkillToolDependency {
+            r#type: "mcp".to_string(),
+            value: "alias-one".to_string(),
+            description: None,
+            transport: Some("streamable_http".to_string()),
+            command: None,
+            url: Some(url.clone()),
+        },
+        SkillToolDependency {
+            r#type: "mcp".to_string(),
+            value: "alias-two".to_string(),
+            description: None,
+            transport: Some("streamable_http".to_string()),
+            command: None,
+            url: Some(url.clone()),
+        },
+    ])];
+
+    let expected = HashMap::from([(
+        "alias-one".to_string(),
+        McpServerConfig {
+            transport: McpServerTransportConfig::StreamableHttp {
+                url,
+                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(),
+        },
+    )]);
+
+    assert_eq!(
+        collect_missing_mcp_dependencies(&skills, &HashMap::new()),
+        expected
+    );
+}

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

@@ -0,0 +1,646 @@
+use super::*;
+use codex_protocol::protocol::GranularApprovalConfig;
+use codex_protocol::protocol::McpAuthStatus;
+use rmcp::model::JsonObject;
+use std::collections::HashSet;
+use std::sync::Arc;
+use tempfile::tempdir;
+
+fn create_test_tool(server_name: &str, tool_name: &str) -> ToolInfo {
+    ToolInfo {
+        server_name: server_name.to_string(),
+        tool_name: tool_name.to_string(),
+        tool_namespace: if server_name == CODEX_APPS_MCP_SERVER_NAME {
+            format!("mcp__{server_name}__")
+        } else {
+            server_name.to_string()
+        },
+        tool: Tool {
+            name: tool_name.to_string().into(),
+            title: None,
+            description: Some(format!("Test tool: {tool_name}").into()),
+            input_schema: Arc::new(JsonObject::default()),
+            output_schema: None,
+            annotations: None,
+            execution: None,
+            icons: None,
+            meta: None,
+        },
+        connector_id: None,
+        connector_name: None,
+        plugin_display_names: Vec::new(),
+        connector_description: None,
+    }
+}
+
+fn create_test_tool_with_connector(
+    server_name: &str,
+    tool_name: &str,
+    connector_id: &str,
+    connector_name: Option<&str>,
+) -> ToolInfo {
+    let mut tool = create_test_tool(server_name, tool_name);
+    tool.connector_id = Some(connector_id.to_string());
+    tool.connector_name = connector_name.map(ToOwned::to_owned);
+    tool
+}
+
+fn create_codex_apps_tools_cache_context(
+    codex_home: PathBuf,
+    account_id: Option<&str>,
+    chatgpt_user_id: Option<&str>,
+) -> CodexAppsToolsCacheContext {
+    CodexAppsToolsCacheContext {
+        codex_home,
+        user_key: CodexAppsToolsCacheKey {
+            account_id: account_id.map(ToOwned::to_owned),
+            chatgpt_user_id: chatgpt_user_id.map(ToOwned::to_owned),
+            is_workspace_account: false,
+        },
+    }
+}
+
+#[test]
+fn elicitation_granular_policy_defaults_to_prompting() {
+    assert!(!elicitation_is_rejected_by_policy(
+        AskForApproval::OnFailure
+    ));
+    assert!(!elicitation_is_rejected_by_policy(
+        AskForApproval::OnRequest
+    ));
+    assert!(!elicitation_is_rejected_by_policy(
+        AskForApproval::UnlessTrusted
+    ));
+    assert!(elicitation_is_rejected_by_policy(AskForApproval::Granular(
+        GranularApprovalConfig {
+            sandbox_approval: true,
+            rules: true,
+            skill_approval: true,
+            request_permissions: true,
+            mcp_elicitations: false,
+        }
+    )));
+}
+
+#[test]
+fn elicitation_granular_policy_respects_never_and_config() {
+    assert!(elicitation_is_rejected_by_policy(AskForApproval::Never));
+    assert!(elicitation_is_rejected_by_policy(AskForApproval::Granular(
+        GranularApprovalConfig {
+            sandbox_approval: true,
+            rules: true,
+            skill_approval: true,
+            request_permissions: true,
+            mcp_elicitations: false,
+        }
+    )));
+}
+
+#[test]
+fn test_qualify_tools_short_non_duplicated_names() {
+    let tools = vec![
+        create_test_tool("server1", "tool1"),
+        create_test_tool("server1", "tool2"),
+    ];
+
+    let qualified_tools = qualify_tools(tools);
+
+    assert_eq!(qualified_tools.len(), 2);
+    assert!(qualified_tools.contains_key("mcp__server1__tool1"));
+    assert!(qualified_tools.contains_key("mcp__server1__tool2"));
+}
+
+#[test]
+fn test_qualify_tools_duplicated_names_skipped() {
+    let tools = vec![
+        create_test_tool("server1", "duplicate_tool"),
+        create_test_tool("server1", "duplicate_tool"),
+    ];
+
+    let qualified_tools = qualify_tools(tools);
+
+    // Only the first tool should remain, the second is skipped
+    assert_eq!(qualified_tools.len(), 1);
+    assert!(qualified_tools.contains_key("mcp__server1__duplicate_tool"));
+}
+
+#[test]
+fn test_qualify_tools_long_names_same_server() {
+    let server_name = "my_server";
+
+    let tools = vec![
+        create_test_tool(
+            server_name,
+            "extremely_lengthy_function_name_that_absolutely_surpasses_all_reasonable_limits",
+        ),
+        create_test_tool(
+            server_name,
+            "yet_another_extremely_lengthy_function_name_that_absolutely_surpasses_all_reasonable_limits",
+        ),
+    ];
+
+    let qualified_tools = qualify_tools(tools);
+
+    assert_eq!(qualified_tools.len(), 2);
+
+    let mut keys: Vec<_> = qualified_tools.keys().cloned().collect();
+    keys.sort();
+
+    assert_eq!(keys[0].len(), 64);
+    assert_eq!(
+        keys[0],
+        "mcp__my_server__extremel119a2b97664e41363932dc84de21e2ff1b93b3e9"
+    );
+
+    assert_eq!(keys[1].len(), 64);
+    assert_eq!(
+        keys[1],
+        "mcp__my_server__yet_anot419a82a89325c1b477274a41f8c65ea5f3a7f341"
+    );
+}
+
+#[test]
+fn test_qualify_tools_sanitizes_invalid_characters() {
+    let tools = vec![create_test_tool("server.one", "tool.two-three")];
+
+    let qualified_tools = qualify_tools(tools);
+
+    assert_eq!(qualified_tools.len(), 1);
+    let (qualified_name, tool) = qualified_tools.into_iter().next().expect("one tool");
+    assert_eq!(qualified_name, "mcp__server_one__tool_two_three");
+
+    // The key is sanitized for OpenAI, but we keep original parts for the actual MCP call.
+    assert_eq!(tool.server_name, "server.one");
+    assert_eq!(tool.tool_name, "tool.two-three");
+
+    assert!(
+        qualified_name
+            .chars()
+            .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-'),
+        "qualified name must be Responses API compatible: {qualified_name:?}"
+    );
+}
+
+#[test]
+fn tool_filter_allows_by_default() {
+    let filter = ToolFilter::default();
+
+    assert!(filter.allows("any"));
+}
+
+#[test]
+fn tool_filter_applies_enabled_list() {
+    let filter = ToolFilter {
+        enabled: Some(HashSet::from(["allowed".to_string()])),
+        disabled: HashSet::new(),
+    };
+
+    assert!(filter.allows("allowed"));
+    assert!(!filter.allows("denied"));
+}
+
+#[test]
+fn tool_filter_applies_disabled_list() {
+    let filter = ToolFilter {
+        enabled: None,
+        disabled: HashSet::from(["blocked".to_string()]),
+    };
+
+    assert!(!filter.allows("blocked"));
+    assert!(filter.allows("open"));
+}
+
+#[test]
+fn tool_filter_applies_enabled_then_disabled() {
+    let filter = ToolFilter {
+        enabled: Some(HashSet::from(["keep".to_string(), "remove".to_string()])),
+        disabled: HashSet::from(["remove".to_string()]),
+    };
+
+    assert!(filter.allows("keep"));
+    assert!(!filter.allows("remove"));
+    assert!(!filter.allows("unknown"));
+}
+
+#[test]
+fn filter_tools_applies_per_server_filters() {
+    let server1_tools = vec![
+        create_test_tool("server1", "tool_a"),
+        create_test_tool("server1", "tool_b"),
+    ];
+    let server2_tools = vec![create_test_tool("server2", "tool_a")];
+    let server1_filter = ToolFilter {
+        enabled: Some(HashSet::from(["tool_a".to_string(), "tool_b".to_string()])),
+        disabled: HashSet::from(["tool_b".to_string()]),
+    };
+    let server2_filter = ToolFilter {
+        enabled: None,
+        disabled: HashSet::from(["tool_a".to_string()]),
+    };
+
+    let filtered: Vec<_> = filter_tools(server1_tools, &server1_filter)
+        .into_iter()
+        .chain(filter_tools(server2_tools, &server2_filter))
+        .collect();
+
+    assert_eq!(filtered.len(), 1);
+    assert_eq!(filtered[0].server_name, "server1");
+    assert_eq!(filtered[0].tool_name, "tool_a");
+}
+
+#[test]
+fn codex_apps_tools_cache_is_overwritten_by_last_write() {
+    let codex_home = tempdir().expect("tempdir");
+    let cache_context = create_codex_apps_tools_cache_context(
+        codex_home.path().to_path_buf(),
+        Some("account-one"),
+        Some("user-one"),
+    );
+    let tools_gateway_1 = vec![create_test_tool(CODEX_APPS_MCP_SERVER_NAME, "one")];
+    let tools_gateway_2 = vec![create_test_tool(CODEX_APPS_MCP_SERVER_NAME, "two")];
+
+    write_cached_codex_apps_tools(&cache_context, &tools_gateway_1);
+    let cached_gateway_1 =
+        read_cached_codex_apps_tools(&cache_context).expect("cache entry exists for first write");
+    assert_eq!(cached_gateway_1[0].tool_name, "one");
+
+    write_cached_codex_apps_tools(&cache_context, &tools_gateway_2);
+    let cached_gateway_2 =
+        read_cached_codex_apps_tools(&cache_context).expect("cache entry exists for second write");
+    assert_eq!(cached_gateway_2[0].tool_name, "two");
+}
+
+#[test]
+fn codex_apps_tools_cache_is_scoped_per_user() {
+    let codex_home = tempdir().expect("tempdir");
+    let cache_context_user_1 = create_codex_apps_tools_cache_context(
+        codex_home.path().to_path_buf(),
+        Some("account-one"),
+        Some("user-one"),
+    );
+    let cache_context_user_2 = create_codex_apps_tools_cache_context(
+        codex_home.path().to_path_buf(),
+        Some("account-two"),
+        Some("user-two"),
+    );
+    let tools_user_1 = vec![create_test_tool(CODEX_APPS_MCP_SERVER_NAME, "one")];
+    let tools_user_2 = vec![create_test_tool(CODEX_APPS_MCP_SERVER_NAME, "two")];
+
+    write_cached_codex_apps_tools(&cache_context_user_1, &tools_user_1);
+    write_cached_codex_apps_tools(&cache_context_user_2, &tools_user_2);
+
+    let read_user_1 =
+        read_cached_codex_apps_tools(&cache_context_user_1).expect("cache entry for user one");
+    let read_user_2 =
+        read_cached_codex_apps_tools(&cache_context_user_2).expect("cache entry for user two");
+
+    assert_eq!(read_user_1[0].tool_name, "one");
+    assert_eq!(read_user_2[0].tool_name, "two");
+    assert_ne!(
+        cache_context_user_1.cache_path(),
+        cache_context_user_2.cache_path(),
+        "each user should get an isolated cache file"
+    );
+}
+
+#[test]
+fn codex_apps_tools_cache_filters_disallowed_connectors() {
+    let codex_home = tempdir().expect("tempdir");
+    let cache_context = create_codex_apps_tools_cache_context(
+        codex_home.path().to_path_buf(),
+        Some("account-one"),
+        Some("user-one"),
+    );
+    let tools = vec![
+        create_test_tool_with_connector(
+            CODEX_APPS_MCP_SERVER_NAME,
+            "blocked_tool",
+            "connector_openai_hidden",
+            Some("Hidden"),
+        ),
+        create_test_tool_with_connector(
+            CODEX_APPS_MCP_SERVER_NAME,
+            "allowed_tool",
+            "calendar",
+            Some("Calendar"),
+        ),
+    ];
+
+    write_cached_codex_apps_tools(&cache_context, &tools);
+    let cached = read_cached_codex_apps_tools(&cache_context).expect("cache entry exists for user");
+
+    assert_eq!(cached.len(), 1);
+    assert_eq!(cached[0].tool_name, "allowed_tool");
+    assert_eq!(cached[0].connector_id.as_deref(), Some("calendar"));
+}
+
+#[test]
+fn codex_apps_tools_cache_is_ignored_when_schema_version_mismatches() {
+    let codex_home = tempdir().expect("tempdir");
+    let cache_context = create_codex_apps_tools_cache_context(
+        codex_home.path().to_path_buf(),
+        Some("account-one"),
+        Some("user-one"),
+    );
+    let cache_path = cache_context.cache_path();
+    if let Some(parent) = cache_path.parent() {
+        std::fs::create_dir_all(parent).expect("create parent");
+    }
+    let bytes = serde_json::to_vec_pretty(&serde_json::json!({
+        "schema_version": CODEX_APPS_TOOLS_CACHE_SCHEMA_VERSION + 1,
+        "tools": [create_test_tool(CODEX_APPS_MCP_SERVER_NAME, "one")],
+    }))
+    .expect("serialize");
+    std::fs::write(cache_path, bytes).expect("write");
+
+    assert!(read_cached_codex_apps_tools(&cache_context).is_none());
+}
+
+#[test]
+fn codex_apps_tools_cache_is_ignored_when_json_is_invalid() {
+    let codex_home = tempdir().expect("tempdir");
+    let cache_context = create_codex_apps_tools_cache_context(
+        codex_home.path().to_path_buf(),
+        Some("account-one"),
+        Some("user-one"),
+    );
+    let cache_path = cache_context.cache_path();
+    if let Some(parent) = cache_path.parent() {
+        std::fs::create_dir_all(parent).expect("create parent");
+    }
+    std::fs::write(cache_path, b"{not json").expect("write");
+
+    assert!(read_cached_codex_apps_tools(&cache_context).is_none());
+}
+
+#[test]
+fn startup_cached_codex_apps_tools_loads_from_disk_cache() {
+    let codex_home = tempdir().expect("tempdir");
+    let cache_context = create_codex_apps_tools_cache_context(
+        codex_home.path().to_path_buf(),
+        Some("account-one"),
+        Some("user-one"),
+    );
+    let cached_tools = vec![create_test_tool(
+        CODEX_APPS_MCP_SERVER_NAME,
+        "calendar_search",
+    )];
+    write_cached_codex_apps_tools(&cache_context, &cached_tools);
+
+    let startup_snapshot = load_startup_cached_codex_apps_tools_snapshot(
+        CODEX_APPS_MCP_SERVER_NAME,
+        Some(&cache_context),
+    );
+    let startup_tools = startup_snapshot.expect("expected startup snapshot to load from cache");
+
+    assert_eq!(startup_tools.len(), 1);
+    assert_eq!(startup_tools[0].server_name, CODEX_APPS_MCP_SERVER_NAME);
+    assert_eq!(startup_tools[0].tool_name, "calendar_search");
+}
+
+#[tokio::test]
+async fn list_all_tools_uses_startup_snapshot_while_client_is_pending() {
+    let startup_tools = vec![create_test_tool(
+        CODEX_APPS_MCP_SERVER_NAME,
+        "calendar_create_event",
+    )];
+    let pending_client = futures::future::pending::<Result<ManagedClient, StartupOutcomeError>>()
+        .boxed()
+        .shared();
+    let approval_policy = Constrained::allow_any(AskForApproval::OnFailure);
+    let mut manager = McpConnectionManager::new_uninitialized(&approval_policy);
+    manager.clients.insert(
+        CODEX_APPS_MCP_SERVER_NAME.to_string(),
+        AsyncManagedClient {
+            client: pending_client,
+            startup_snapshot: Some(startup_tools),
+            startup_complete: Arc::new(std::sync::atomic::AtomicBool::new(false)),
+            tool_plugin_provenance: Arc::new(ToolPluginProvenance::default()),
+        },
+    );
+
+    let tools = manager.list_all_tools().await;
+    let tool = tools
+        .get("mcp__codex_apps__calendar_create_event")
+        .expect("tool from startup cache");
+    assert_eq!(tool.server_name, CODEX_APPS_MCP_SERVER_NAME);
+    assert_eq!(tool.tool_name, "calendar_create_event");
+}
+
+#[tokio::test]
+async fn list_all_tools_blocks_while_client_is_pending_without_startup_snapshot() {
+    let pending_client = futures::future::pending::<Result<ManagedClient, StartupOutcomeError>>()
+        .boxed()
+        .shared();
+    let approval_policy = Constrained::allow_any(AskForApproval::OnFailure);
+    let mut manager = McpConnectionManager::new_uninitialized(&approval_policy);
+    manager.clients.insert(
+        CODEX_APPS_MCP_SERVER_NAME.to_string(),
+        AsyncManagedClient {
+            client: pending_client,
+            startup_snapshot: None,
+            startup_complete: Arc::new(std::sync::atomic::AtomicBool::new(false)),
+            tool_plugin_provenance: Arc::new(ToolPluginProvenance::default()),
+        },
+    );
+
+    let timeout_result =
+        tokio::time::timeout(Duration::from_millis(10), manager.list_all_tools()).await;
+    assert!(timeout_result.is_err());
+}
+
+#[tokio::test]
+async fn list_all_tools_does_not_block_when_startup_snapshot_cache_hit_is_empty() {
+    let pending_client = futures::future::pending::<Result<ManagedClient, StartupOutcomeError>>()
+        .boxed()
+        .shared();
+    let approval_policy = Constrained::allow_any(AskForApproval::OnFailure);
+    let mut manager = McpConnectionManager::new_uninitialized(&approval_policy);
+    manager.clients.insert(
+        CODEX_APPS_MCP_SERVER_NAME.to_string(),
+        AsyncManagedClient {
+            client: pending_client,
+            startup_snapshot: Some(Vec::new()),
+            startup_complete: Arc::new(std::sync::atomic::AtomicBool::new(false)),
+            tool_plugin_provenance: Arc::new(ToolPluginProvenance::default()),
+        },
+    );
+
+    let timeout_result =
+        tokio::time::timeout(Duration::from_millis(10), manager.list_all_tools()).await;
+    let tools = timeout_result.expect("cache-hit startup snapshot should not block");
+    assert!(tools.is_empty());
+}
+
+#[tokio::test]
+async fn list_all_tools_uses_startup_snapshot_when_client_startup_fails() {
+    let startup_tools = vec![create_test_tool(
+        CODEX_APPS_MCP_SERVER_NAME,
+        "calendar_create_event",
+    )];
+    let failed_client = futures::future::ready::<Result<ManagedClient, StartupOutcomeError>>(Err(
+        StartupOutcomeError::Failed {
+            error: "startup failed".to_string(),
+        },
+    ))
+    .boxed()
+    .shared();
+    let approval_policy = Constrained::allow_any(AskForApproval::OnFailure);
+    let mut manager = McpConnectionManager::new_uninitialized(&approval_policy);
+    let startup_complete = Arc::new(std::sync::atomic::AtomicBool::new(true));
+    manager.clients.insert(
+        CODEX_APPS_MCP_SERVER_NAME.to_string(),
+        AsyncManagedClient {
+            client: failed_client,
+            startup_snapshot: Some(startup_tools),
+            startup_complete,
+            tool_plugin_provenance: Arc::new(ToolPluginProvenance::default()),
+        },
+    );
+
+    let tools = manager.list_all_tools().await;
+    let tool = tools
+        .get("mcp__codex_apps__calendar_create_event")
+        .expect("tool from startup cache");
+    assert_eq!(tool.server_name, CODEX_APPS_MCP_SERVER_NAME);
+    assert_eq!(tool.tool_name, "calendar_create_event");
+}
+
+#[test]
+fn elicitation_capability_enabled_only_for_codex_apps() {
+    let codex_apps_capability = elicitation_capability_for_server(CODEX_APPS_MCP_SERVER_NAME);
+    assert!(matches!(
+        codex_apps_capability,
+        Some(ElicitationCapability {
+            form: Some(FormElicitationCapability {
+                schema_validation: None
+            }),
+            url: None,
+        })
+    ));
+
+    assert!(elicitation_capability_for_server("custom_mcp").is_none());
+}
+
+#[test]
+fn mcp_init_error_display_prompts_for_github_pat() {
+    let server_name = "github";
+    let entry = McpAuthStatusEntry {
+        config: McpServerConfig {
+            transport: McpServerTransportConfig::StreamableHttp {
+                url: "https://api.githubcopilot.com/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(),
+        },
+        auth_status: McpAuthStatus::Unsupported,
+    };
+    let err: StartupOutcomeError = anyhow::anyhow!("OAuth is unsupported").into();
+
+    let display = mcp_init_error_display(server_name, Some(&entry), &err);
+
+    let expected = format!(
+        "GitHub MCP does not support OAuth. Log in by adding a personal access token (https://github.com/settings/personal-access-tokens) to your environment and config.toml:\n[mcp_servers.{server_name}]\nbearer_token_env_var = CODEX_GITHUB_PERSONAL_ACCESS_TOKEN"
+    );
+
+    assert_eq!(expected, display);
+}
+
+#[test]
+fn mcp_init_error_display_prompts_for_login_when_auth_required() {
+    let server_name = "example";
+    let err: StartupOutcomeError = anyhow::anyhow!("Auth required for server").into();
+
+    let display = mcp_init_error_display(server_name, /*entry*/ None, &err);
+
+    let expected = format!(
+        "The {server_name} MCP server is not logged in. Run `codex mcp login {server_name}`."
+    );
+
+    assert_eq!(expected, display);
+}
+
+#[test]
+fn mcp_init_error_display_reports_generic_errors() {
+    let server_name = "custom";
+    let entry = McpAuthStatusEntry {
+        config: McpServerConfig {
+            transport: McpServerTransportConfig::StreamableHttp {
+                url: "https://example.com".to_string(),
+                bearer_token_env_var: Some("TOKEN".to_string()),
+                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(),
+        },
+        auth_status: McpAuthStatus::Unsupported,
+    };
+    let err: StartupOutcomeError = anyhow::anyhow!("boom").into();
+
+    let display = mcp_init_error_display(server_name, Some(&entry), &err);
+
+    let expected = format!("MCP client for `{server_name}` failed to start: {err:#}");
+
+    assert_eq!(expected, display);
+}
+
+#[test]
+fn mcp_init_error_display_includes_startup_timeout_hint() {
+    let server_name = "slow";
+    let err: StartupOutcomeError = anyhow::anyhow!("request timed out").into();
+
+    let display = mcp_init_error_display(server_name, /*entry*/ None, &err);
+
+    assert_eq!(
+        "MCP client for `slow` timed out after 30 seconds. Add or adjust `startup_timeout_sec` in your config.toml:\n[mcp_servers.slow]\nstartup_timeout_sec = XX",
+        display
+    );
+}
+
+#[test]
+fn transport_origin_extracts_http_origin() {
+    let transport = McpServerTransportConfig::StreamableHttp {
+        url: "https://example.com:8443/path?query=1".to_string(),
+        bearer_token_env_var: None,
+        http_headers: None,
+        env_http_headers: None,
+    };
+
+    assert_eq!(
+        transport_origin(&transport),
+        Some("https://example.com:8443".to_string())
+    );
+}
+
+#[test]
+fn transport_origin_is_stdio_for_stdio_transport() {
+    let transport = McpServerTransportConfig::Stdio {
+        command: "server".to_string(),
+        args: Vec::new(),
+        env: None,
+        env_vars: Vec::new(),
+        cwd: None,
+    };
+
+    assert_eq!(transport_origin(&transport), Some("stdio".to_string()));
+}