[MCP] Add an enabled config field (#4917)

This lets users more easily toggle MCP servers.

codex-rs/core/src/config.rs

@@ -401,6 +401,10 @@ pub fn write_global_mcp_servers(
                 }
             }
 
+            if !config.enabled {
+                entry["enabled"] = toml_edit::value(false);
+            }
+
             if let Some(timeout) = config.startup_timeout_sec {
                 entry["startup_timeout_sec"] = toml_edit::value(timeout.as_secs_f64());
             }
@@ -1515,6 +1519,7 @@ exclude_slash_tmp = true
                     args: vec!["hello".to_string()],
                     env: None,
                 },
+                enabled: true,
                 startup_timeout_sec: Some(Duration::from_secs(3)),
                 tool_timeout_sec: Some(Duration::from_secs(5)),
             },
@@ -1535,6 +1540,7 @@ exclude_slash_tmp = true
         }
         assert_eq!(docs.startup_timeout_sec, Some(Duration::from_secs(3)));
         assert_eq!(docs.tool_timeout_sec, Some(Duration::from_secs(5)));
+        assert!(docs.enabled);
 
         let empty = BTreeMap::new();
         write_global_mcp_servers(codex_home.path(), &empty)?;
@@ -1639,6 +1645,7 @@ bearer_token = "secret"
                         ("ALPHA_VAR".to_string(), "1".to_string()),
                     ])),
                 },
+                enabled: true,
                 startup_timeout_sec: None,
                 tool_timeout_sec: None,
             },
@@ -1689,6 +1696,7 @@ ZIG_VAR = "3"
                     url: "https://example.com/mcp".to_string(),
                     bearer_token_env_var: Some("MCP_TOKEN".to_string()),
                 },
+                enabled: true,
                 startup_timeout_sec: Some(Duration::from_secs(2)),
                 tool_timeout_sec: None,
             },
@@ -1728,6 +1736,7 @@ startup_timeout_sec = 2.0
                     url: "https://example.com/mcp".to_string(),
                     bearer_token_env_var: None,
                 },
+                enabled: true,
                 startup_timeout_sec: None,
                 tool_timeout_sec: None,
             },
@@ -1758,6 +1767,40 @@ url = "https://example.com/mcp"
         Ok(())
     }
 
+    #[tokio::test]
+    async fn write_global_mcp_servers_serializes_disabled_flag() -> anyhow::Result<()> {
+        let codex_home = TempDir::new()?;
+
+        let servers = BTreeMap::from([(
+            "docs".to_string(),
+            McpServerConfig {
+                transport: McpServerTransportConfig::Stdio {
+                    command: "docs-server".to_string(),
+                    args: Vec::new(),
+                    env: None,
+                },
+                enabled: false,
+                startup_timeout_sec: None,
+                tool_timeout_sec: None,
+            },
+        )]);
+
+        write_global_mcp_servers(codex_home.path(), &servers)?;
+
+        let config_path = codex_home.path().join(CONFIG_TOML_FILE);
+        let serialized = std::fs::read_to_string(&config_path)?;
+        assert!(
+            serialized.contains("enabled = false"),
+            "serialized config missing disabled flag:\n{serialized}"
+        );
+
+        let loaded = load_global_mcp_servers(codex_home.path()).await?;
+        let docs = loaded.get("docs").expect("docs entry");
+        assert!(!docs.enabled);
+
+        Ok(())
+    }
+
     #[tokio::test]
     async fn persist_model_selection_updates_defaults() -> anyhow::Result<()> {
         let codex_home = TempDir::new()?;

codex-rs/core/src/config_types.rs

@@ -20,6 +20,10 @@ pub struct McpServerConfig {
     #[serde(flatten)]
     pub transport: McpServerTransportConfig,
 
+    /// When `false`, Codex skips initializing this MCP server.
+    #[serde(default = "default_enabled")]
+    pub enabled: bool,
+
     /// Startup timeout in seconds for initializing MCP server & initially listing tools.
     #[serde(
         default,
@@ -56,6 +60,8 @@ impl<'de> Deserialize<'de> for McpServerConfig {
             startup_timeout_ms: Option<u64>,
             #[serde(default, with = "option_duration_secs")]
             tool_timeout_sec: Option<Duration>,
+            #[serde(default)]
+            enabled: Option<bool>,
         }
 
         let raw = RawMcpServerConfig::deserialize(deserializer)?;
@@ -127,10 +133,15 @@ impl<'de> Deserialize<'de> for McpServerConfig {
             transport,
             startup_timeout_sec,
             tool_timeout_sec: raw.tool_timeout_sec,
+            enabled: raw.enabled.unwrap_or_else(default_enabled),
         })
     }
 }
 
+const fn default_enabled() -> bool {
+    true
+}
+
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
 #[serde(untagged, deny_unknown_fields, rename_all = "snake_case")]
 pub enum McpServerTransportConfig {
@@ -460,6 +471,7 @@ mod tests {
                 env: None
             }
         );
+        assert!(cfg.enabled);
     }
 
     #[test]
@@ -480,6 +492,7 @@ mod tests {
                 env: None
             }
         );
+        assert!(cfg.enabled);
     }
 
     #[test]
@@ -501,6 +514,20 @@ mod tests {
                 env: Some(HashMap::from([("FOO".to_string(), "BAR".to_string())]))
             }
         );
+        assert!(cfg.enabled);
+    }
+
+    #[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);
     }
 
     #[test]
@@ -519,6 +546,7 @@ mod tests {
                 bearer_token_env_var: None
             }
         );
+        assert!(cfg.enabled);
     }
 
     #[test]
@@ -538,6 +566,7 @@ mod tests {
                 bearer_token_env_var: Some("GITHUB_TOKEN".to_string())
             }
         );
+        assert!(cfg.enabled);
     }
 
     #[test]

codex-rs/core/src/mcp_connection_manager.rs

@@ -207,6 +207,10 @@ impl McpConnectionManager {
                 continue;
             }
 
+            if !cfg.enabled {
+                continue;
+            }
+
             let startup_timeout = cfg.startup_timeout_sec.unwrap_or(DEFAULT_STARTUP_TIMEOUT);
             let tool_timeout = cfg.tool_timeout_sec.unwrap_or(DEFAULT_TOOL_TIMEOUT);