✨ feat(mcp): add project-scoped MCP server configuration support

WHAT: Add project-scoped MCP server configuration support allowing .codex/config.toml in projects
WHY: Enable fine-grained configuration management per project, avoiding global config pollution and supporting project-specific toolchain requirements
HOW: Extend mcp command with --project flag; implement project config loading and merging logic; add CRUD operations for project-level configs; update documentation and README; validate functionality with unit tests

Author: LaelLuo

README.md

@@ -63,7 +63,9 @@ You can also use Codex with an API key, but this requires [additional setup](./d
 
 ### Model Context Protocol (MCP)
 
-Codex CLI supports [MCP servers](./docs/advanced.md#model-context-protocol-mcp). Enable by adding an `mcp_servers` section to your `~/.codex/config.toml`.
+Codex CLI supports [MCP servers](./docs/advanced.md#model-context-protocol-mcp).
+Configure them globally via the `mcp_servers` section in `~/.codex/config.toml`,
+or per-project in `./.codex/config.toml` inside your project.
 
 
 ### Configuration

codex-rs/Cargo.lock

@@ -28,6 +28,7 @@ codex-mcp-server = { path = "../mcp-server" }
 codex-protocol = { path = "../protocol" }
 codex-tui = { path = "../tui" }
 serde_json = "1"
+toml_edit = "0.23.4"
 tokio = { version = "1", features = [
     "io-std",
     "macros",
@@ -44,3 +45,4 @@ assert_cmd = "2"
 predicates = "3"
 pretty_assertions = "1"
 tempfile = "3"
+toml = "0.9.5"

codex-rs/cli/Cargo.toml

@@ -13,6 +13,7 @@ use codex_core::config::find_codex_home;
 use codex_core::config::load_global_mcp_servers;
 use codex_core::config::write_global_mcp_servers;
 use codex_core::config_types::McpServerConfig;
+use codex_core::git_info::resolve_root_git_project_for_trust;
 
 /// [experimental] Launch Codex as an MCP server or manage configured MCP servers.
 ///
@@ -78,12 +79,20 @@ pub struct AddArgs {
     /// Command to launch the MCP server.
     #[arg(trailing_var_arg = true, num_args = 1..)]
     pub command: Vec<String>,
+
+    /// Write this server to the project's `.codex/config.toml` instead of global config.
+    #[arg(long)]
+    pub project: bool,
 }
 
 #[derive(Debug, clap::Parser)]
 pub struct RemoveArgs {
     /// Name of the MCP server configuration to remove.
     pub name: String,
+
+    /// Remove from the project's `.codex/config.toml` instead of global config.
+    #[arg(long)]
+    pub project: bool,
 }
 
 impl McpCli {
@@ -120,7 +129,12 @@ fn run_add(config_overrides: &CliConfigOverrides, add_args: AddArgs) -> Result<(
     // Validate any provided overrides even though they are not currently applied.
     config_overrides.parse_overrides().map_err(|e| anyhow!(e))?;
 
-    let AddArgs { name, env, command } = add_args;
+    let AddArgs {
+        name,
+        env,
+        command,
+        project,
+    } = add_args;
 
     validate_server_name(&name)?;
 
@@ -140,6 +154,26 @@ fn run_add(config_overrides: &CliConfigOverrides, add_args: AddArgs) -> Result<(
         Some(map)
     };
 
+    if project {
+        let cwd = std::env::current_dir().context("failed to get current directory")?;
+        let project_root = resolve_root_git_project_for_trust(&cwd).unwrap_or(cwd);
+        add_project_mcp_server(
+            &project_root,
+            &name,
+            McpServerConfig {
+                command: command_bin,
+                args: command_args,
+                env: env_map,
+                startup_timeout_ms: None,
+            },
+        )?;
+        println!(
+            "Added project MCP server '{name}' in {}/.codex.",
+            project_root.display()
+        );
+        return Ok(());
+    }
+
     let codex_home = find_codex_home().context("failed to resolve CODEX_HOME")?;
     let mut servers = load_global_mcp_servers(&codex_home)
         .with_context(|| format!("failed to load MCP servers from {}", codex_home.display()))?;
@@ -164,10 +198,25 @@ fn run_add(config_overrides: &CliConfigOverrides, add_args: AddArgs) -> Result<(
 fn run_remove(config_overrides: &CliConfigOverrides, remove_args: RemoveArgs) -> Result<()> {
     config_overrides.parse_overrides().map_err(|e| anyhow!(e))?;
 
-    let RemoveArgs { name } = remove_args;
+    let RemoveArgs { name, project } = remove_args;
 
     validate_server_name(&name)?;
 
+    if project {
+        let cwd = std::env::current_dir().context("failed to get current directory")?;
+        let project_root = resolve_root_git_project_for_trust(&cwd).unwrap_or(cwd);
+        let removed = remove_project_mcp_server(&project_root, &name)?;
+        if removed {
+            println!(
+                "Removed project MCP server '{name}' in {}/.codex.",
+                project_root.display()
+            );
+        } else {
+            println!("No MCP server named '{name}' found.");
+        }
+        return Ok(());
+    }
+
     let codex_home = find_codex_home().context("failed to resolve CODEX_HOME")?;
     let mut servers = load_global_mcp_servers(&codex_home)
         .with_context(|| format!("failed to load MCP servers from {}", codex_home.display()))?;
@@ -188,6 +237,90 @@ fn run_remove(config_overrides: &CliConfigOverrides, remove_args: RemoveArgs) ->
     Ok(())
 }
 
+fn ensure_project_codex_path(project_root: &std::path::Path) -> Result<std::path::PathBuf> {
+    let codex_dir = project_root.join(".codex");
+    std::fs::create_dir_all(&codex_dir)
+        .with_context(|| format!("failed to create {}", codex_dir.display()))?;
+    Ok(codex_dir.join("config.toml"))
+}
+
+fn add_project_mcp_server(
+    project_root: &std::path::Path,
+    name: &str,
+    entry: McpServerConfig,
+) -> Result<()> {
+    use toml_edit::{Array as TomlArray, DocumentMut, Item as TomlItem, Table as TomlTable, value};
+
+    let path = ensure_project_codex_path(project_root)?;
+    let mut doc = match std::fs::read_to_string(&path) {
+        Ok(contents) => contents.parse::<DocumentMut>().map_err(|e| anyhow!(e))?,
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => DocumentMut::new(),
+        Err(e) => return Err(anyhow!(e)),
+    };
+
+    if !doc.as_table().contains_key("mcp_servers") || doc["mcp_servers"].as_table().is_none() {
+        let mut table = TomlTable::new();
+        table.set_implicit(true);
+        doc["mcp_servers"] = TomlItem::Table(table);
+    }
+
+    let mut entry_tbl = TomlTable::new();
+    entry_tbl.set_implicit(false);
+    entry_tbl["command"] = value(entry.command);
+
+    if !entry.args.is_empty() {
+        let mut args = TomlArray::new();
+        for a in entry.args {
+            args.push(a);
+        }
+        entry_tbl["args"] = TomlItem::Value(args.into());
+    }
+
+    if let Some(env) = entry.env {
+        if !env.is_empty() {
+            let mut env_tbl = TomlTable::new();
+            env_tbl.set_implicit(false);
+            let mut pairs: Vec<_> = env.into_iter().collect();
+            pairs.sort_by(|(a, _), (b, _)| a.cmp(&b));
+            for (k, v) in pairs {
+                env_tbl.insert(&k, value(v));
+            }
+            entry_tbl["env"] = TomlItem::Table(env_tbl);
+        }
+    }
+
+    if let Some(timeout) = entry.startup_timeout_ms {
+        let timeout = i64::try_from(timeout).context("startup_timeout_ms too large")?;
+        entry_tbl["startup_timeout_ms"] = value(timeout);
+    }
+
+    doc["mcp_servers"][name] = TomlItem::Table(entry_tbl);
+    std::fs::write(&path, doc.to_string())
+        .with_context(|| format!("failed to write {}", path.display()))?;
+    Ok(())
+}
+
+fn remove_project_mcp_server(project_root: &std::path::Path, name: &str) -> Result<bool> {
+    use toml_edit::DocumentMut;
+    let path = project_root.join(".codex").join("config.toml");
+    let contents = match std::fs::read_to_string(&path) {
+        Ok(c) => c,
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(false),
+        Err(e) => return Err(anyhow!(e)),
+    };
+
+    let mut doc = contents.parse::<DocumentMut>().map_err(|e| anyhow!(e))?;
+    let Some(mcp_tbl) = doc["mcp_servers"].as_table_mut() else {
+        return Ok(false);
+    };
+    let removed = mcp_tbl.remove(name).is_some();
+    if removed {
+        std::fs::write(&path, doc.to_string())
+            .with_context(|| format!("failed to write {}", path.display()))?;
+    }
+    Ok(removed)
+}
+
 fn run_list(config_overrides: &CliConfigOverrides, list_args: ListArgs) -> Result<()> {
     let overrides = config_overrides.parse_overrides().map_err(|e| anyhow!(e))?;
     let config = Config::load_with_cli_overrides(overrides, ConfigOverrides::default())

codex-rs/cli/src/mcp_cmd.rs

@@ -0,0 +1,69 @@
+use std::path::Path;
+
+use anyhow::Result;
+use predicates::str::contains;
+use tempfile::TempDir;
+
+fn codex_command(codex_home: &Path) -> Result<assert_cmd::Command> {
+    let mut cmd = assert_cmd::Command::cargo_bin("codex")?;
+    cmd.env("CODEX_HOME", codex_home);
+    Ok(cmd)
+}
+
+#[test]
+fn add_and_remove_project_scoped_server() -> Result<()> {
+    let codex_home = TempDir::new()?;
+    let project_dir = TempDir::new()?;
+
+    // Add project-scoped server (writes into <project>/.codex/config.toml)
+    let mut add_cmd = codex_command(codex_home.path())?;
+    add_cmd
+        .current_dir(project_dir.path())
+        .args(["mcp", "add", "docs", "--project", "--", "echo", "hello"])
+        .assert()
+        .success()
+        .stdout(contains("Added project MCP server 'docs'"));
+
+    // Verify the project file contents
+    let project_toml =
+        std::fs::read_to_string(project_dir.path().join(".codex").join("config.toml"))?;
+    let parsed: toml::Value = toml::from_str(&project_toml)?;
+    let mcp = parsed
+        .get("mcp_servers")
+        .and_then(|v| v.as_table())
+        .expect("mcp_servers table");
+    let docs = mcp
+        .get("docs")
+        .and_then(|v| v.as_table())
+        .expect("docs entry");
+    assert_eq!(docs.get("command").and_then(|v| v.as_str()), Some("echo"));
+    let args = docs
+        .get("args")
+        .and_then(|v| v.as_array())
+        .expect("args array");
+    assert_eq!(
+        args.iter().map(|v| v.as_str().unwrap()).collect::<Vec<_>>(),
+        vec!["hello"]
+    );
+
+    // Remove project-scoped server
+    let mut remove_cmd = codex_command(codex_home.path())?;
+    remove_cmd
+        .current_dir(project_dir.path())
+        .args(["mcp", "remove", "docs", "--project"])
+        .assert()
+        .success()
+        .stdout(contains("Removed project MCP server 'docs'"));
+
+    let project_toml =
+        std::fs::read_to_string(project_dir.path().join(".codex").join("config.toml"))?;
+    let parsed_after: toml::Value = toml::from_str(&project_toml)?;
+    let mcp_after = parsed_after
+        .get("mcp_servers")
+        .and_then(|v| v.as_table())
+        .cloned()
+        .unwrap_or_default();
+    assert!(!mcp_after.contains_key("docs"));
+
+    Ok(())
+}