initial mcp add interface (#3543)

Adds `codex mcp add`, `codex mcp list`, `codex mcp remove`. Currently writes to global config.

codex-rs/cli/Cargo.toml

@@ -38,3 +38,9 @@ tokio = { version = "1", features = [
 tracing = "0.1.41"
 tracing-subscriber = "0.3.19"
 codex-protocol-ts = { path = "../protocol-ts" }
+
+[dev-dependencies]
+assert_cmd = "2"
+predicates = "3"
+pretty_assertions = "1"
+tempfile = "3"

codex-rs/cli/src/main.rs

@@ -17,6 +17,9 @@ use codex_exec::Cli as ExecCli;
 use codex_tui::Cli as TuiCli;
 use std::path::PathBuf;
 
+mod mcp_cmd;
+
+use crate::mcp_cmd::McpCli;
 use crate::proto::ProtoCli;
 
 /// Codex CLI
@@ -56,8 +59,8 @@ enum Subcommand {
     /// Remove stored authentication credentials.
     Logout(LogoutCommand),
 
-    /// Experimental: run Codex as an MCP server.
-    Mcp,
+    /// [experimental] Run Codex as an MCP server and manage MCP servers.
+    Mcp(McpCli),
 
     /// Run the Protocol stream via stdin/stdout
     #[clap(visible_alias = "p")]
@@ -182,9 +185,10 @@ async fn cli_main(codex_linux_sandbox_exe: Option<PathBuf>) -> anyhow::Result<()
             );
             codex_exec::run_main(exec_cli, codex_linux_sandbox_exe).await?;
         }
-        Some(Subcommand::Mcp) => {
-            codex_mcp_server::run_main(codex_linux_sandbox_exe, root_config_overrides.clone())
-                .await?;
+        Some(Subcommand::Mcp(mut mcp_cli)) => {
+            // Propagate any root-level config overrides (e.g. `-c key=value`).
+            prepend_config_flags(&mut mcp_cli.config_overrides, root_config_overrides.clone());
+            mcp_cli.run(codex_linux_sandbox_exe).await?;
         }
         Some(Subcommand::Resume(ResumeCommand { session_id, last })) => {
             // Start with the parsed interactive CLI so resume shares the same

codex-rs/cli/src/mcp_cmd.rs

@@ -0,0 +1,370 @@
+use std::collections::BTreeMap;
+use std::collections::HashMap;
+use std::path::PathBuf;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::anyhow;
+use anyhow::bail;
+use codex_common::CliConfigOverrides;
+use codex_core::config::Config;
+use codex_core::config::ConfigOverrides;
+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;
+
+/// [experimental] Launch Codex as an MCP server or manage configured MCP servers.
+///
+/// Subcommands:
+/// - `serve`  — run the MCP server on stdio
+/// - `list`   — list configured servers (with `--json`)
+/// - `get`    — show a single server (with `--json`)
+/// - `add`    — add a server launcher entry to `~/.codex/config.toml`
+/// - `remove` — delete a server entry
+#[derive(Debug, clap::Parser)]
+pub struct McpCli {
+    #[clap(flatten)]
+    pub config_overrides: CliConfigOverrides,
+
+    #[command(subcommand)]
+    pub cmd: Option<McpSubcommand>,
+}
+
+#[derive(Debug, clap::Subcommand)]
+pub enum McpSubcommand {
+    /// [experimental] Run the Codex MCP server (stdio transport).
+    Serve,
+
+    /// [experimental] List configured MCP servers.
+    List(ListArgs),
+
+    /// [experimental] Show details for a configured MCP server.
+    Get(GetArgs),
+
+    /// [experimental] Add a global MCP server entry.
+    Add(AddArgs),
+
+    /// [experimental] Remove a global MCP server entry.
+    Remove(RemoveArgs),
+}
+
+#[derive(Debug, clap::Parser)]
+pub struct ListArgs {
+    /// Output the configured servers as JSON.
+    #[arg(long)]
+    pub json: bool,
+}
+
+#[derive(Debug, clap::Parser)]
+pub struct GetArgs {
+    /// Name of the MCP server to display.
+    pub name: String,
+
+    /// Output the server configuration as JSON.
+    #[arg(long)]
+    pub json: bool,
+}
+
+#[derive(Debug, clap::Parser)]
+pub struct AddArgs {
+    /// Name for the MCP server configuration.
+    pub name: String,
+
+    /// Environment variables to set when launching the server.
+    #[arg(long, value_parser = parse_env_pair, value_name = "KEY=VALUE")]
+    pub env: Vec<(String, String)>,
+
+    /// Command to launch the MCP server.
+    #[arg(trailing_var_arg = true, num_args = 1..)]
+    pub command: Vec<String>,
+}
+
+#[derive(Debug, clap::Parser)]
+pub struct RemoveArgs {
+    /// Name of the MCP server configuration to remove.
+    pub name: String,
+}
+
+impl McpCli {
+    pub async fn run(self, codex_linux_sandbox_exe: Option<PathBuf>) -> Result<()> {
+        let McpCli {
+            config_overrides,
+            cmd,
+        } = self;
+        let subcommand = cmd.unwrap_or(McpSubcommand::Serve);
+
+        match subcommand {
+            McpSubcommand::Serve => {
+                codex_mcp_server::run_main(codex_linux_sandbox_exe, config_overrides).await?;
+            }
+            McpSubcommand::List(args) => {
+                run_list(&config_overrides, args)?;
+            }
+            McpSubcommand::Get(args) => {
+                run_get(&config_overrides, args)?;
+            }
+            McpSubcommand::Add(args) => {
+                run_add(&config_overrides, args)?;
+            }
+            McpSubcommand::Remove(args) => {
+                run_remove(&config_overrides, args)?;
+            }
+        }
+
+        Ok(())
+    }
+}
+
+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;
+
+    validate_server_name(&name)?;
+
+    let mut command_parts = command.into_iter();
+    let command_bin = command_parts
+        .next()
+        .ok_or_else(|| anyhow!("command is required"))?;
+    let command_args: Vec<String> = command_parts.collect();
+
+    let env_map = if env.is_empty() {
+        None
+    } else {
+        let mut map = HashMap::new();
+        for (key, value) in env {
+            map.insert(key, value);
+        }
+        Some(map)
+    };
+
+    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()))?;
+
+    let new_entry = McpServerConfig {
+        command: command_bin,
+        args: command_args,
+        env: env_map,
+        startup_timeout_ms: None,
+    };
+
+    servers.insert(name.clone(), new_entry);
+
+    write_global_mcp_servers(&codex_home, &servers)
+        .with_context(|| format!("failed to write MCP servers to {}", codex_home.display()))?;
+
+    println!("Added global MCP server '{name}'.");
+
+    Ok(())
+}
+
+fn run_remove(config_overrides: &CliConfigOverrides, remove_args: RemoveArgs) -> Result<()> {
+    config_overrides.parse_overrides().map_err(|e| anyhow!(e))?;
+
+    let RemoveArgs { name } = remove_args;
+
+    validate_server_name(&name)?;
+
+    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()))?;
+
+    let removed = servers.remove(&name).is_some();
+
+    if removed {
+        write_global_mcp_servers(&codex_home, &servers)
+            .with_context(|| format!("failed to write MCP servers to {}", codex_home.display()))?;
+    }
+
+    if removed {
+        println!("Removed global MCP server '{name}'.");
+    } else {
+        println!("No MCP server named '{name}' found.");
+    }
+
+    Ok(())
+}
+
+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())
+        .context("failed to load configuration")?;
+
+    let mut entries: Vec<_> = config.mcp_servers.iter().collect();
+    entries.sort_by(|(a, _), (b, _)| a.cmp(b));
+
+    if list_args.json {
+        let json_entries: Vec<_> = entries
+            .into_iter()
+            .map(|(name, cfg)| {
+                let env = cfg.env.as_ref().map(|env| {
+                    env.iter()
+                        .map(|(k, v)| (k.clone(), v.clone()))
+                        .collect::<BTreeMap<_, _>>()
+                });
+                serde_json::json!({
+                    "name": name,
+                    "command": cfg.command,
+                    "args": cfg.args,
+                    "env": env,
+                    "startup_timeout_ms": cfg.startup_timeout_ms,
+                })
+            })
+            .collect();
+        let output = serde_json::to_string_pretty(&json_entries)?;
+        println!("{output}");
+        return Ok(());
+    }
+
+    if entries.is_empty() {
+        println!("No MCP servers configured yet. Try `codex mcp add my-tool -- my-command`.");
+        return Ok(());
+    }
+
+    let mut rows: Vec<[String; 4]> = Vec::new();
+    for (name, cfg) in entries {
+        let args = if cfg.args.is_empty() {
+            "-".to_string()
+        } else {
+            cfg.args.join(" ")
+        };
+
+        let env = match cfg.env.as_ref() {
+            None => "-".to_string(),
+            Some(map) if map.is_empty() => "-".to_string(),
+            Some(map) => {
+                let mut pairs: Vec<_> = map.iter().collect();
+                pairs.sort_by(|(a, _), (b, _)| a.cmp(b));
+                pairs
+                    .into_iter()
+                    .map(|(k, v)| format!("{k}={v}"))
+                    .collect::<Vec<_>>()
+                    .join(", ")
+            }
+        };
+
+        rows.push([name.clone(), cfg.command.clone(), args, env]);
+    }
+
+    let mut widths = ["Name".len(), "Command".len(), "Args".len(), "Env".len()];
+    for row in &rows {
+        for (i, cell) in row.iter().enumerate() {
+            widths[i] = widths[i].max(cell.len());
+        }
+    }
+
+    println!(
+        "{:<name_w$}  {:<cmd_w$}  {:<args_w$}  {:<env_w$}",
+        "Name",
+        "Command",
+        "Args",
+        "Env",
+        name_w = widths[0],
+        cmd_w = widths[1],
+        args_w = widths[2],
+        env_w = widths[3],
+    );
+
+    for row in rows {
+        println!(
+            "{:<name_w$}  {:<cmd_w$}  {:<args_w$}  {:<env_w$}",
+            row[0],
+            row[1],
+            row[2],
+            row[3],
+            name_w = widths[0],
+            cmd_w = widths[1],
+            args_w = widths[2],
+            env_w = widths[3],
+        );
+    }
+
+    Ok(())
+}
+
+fn run_get(config_overrides: &CliConfigOverrides, get_args: GetArgs) -> Result<()> {
+    let overrides = config_overrides.parse_overrides().map_err(|e| anyhow!(e))?;
+    let config = Config::load_with_cli_overrides(overrides, ConfigOverrides::default())
+        .context("failed to load configuration")?;
+
+    let Some(server) = config.mcp_servers.get(&get_args.name) else {
+        bail!("No MCP server named '{name}' found.", name = get_args.name);
+    };
+
+    if get_args.json {
+        let env = server.env.as_ref().map(|env| {
+            env.iter()
+                .map(|(k, v)| (k.clone(), v.clone()))
+                .collect::<BTreeMap<_, _>>()
+        });
+        let output = serde_json::to_string_pretty(&serde_json::json!({
+            "name": get_args.name,
+            "command": server.command,
+            "args": server.args,
+            "env": env,
+            "startup_timeout_ms": server.startup_timeout_ms,
+        }))?;
+        println!("{output}");
+        return Ok(());
+    }
+
+    println!("{}", get_args.name);
+    println!("  command: {}", server.command);
+    let args = if server.args.is_empty() {
+        "-".to_string()
+    } else {
+        server.args.join(" ")
+    };
+    println!("  args: {args}");
+    let env_display = match server.env.as_ref() {
+        None => "-".to_string(),
+        Some(map) if map.is_empty() => "-".to_string(),
+        Some(map) => {
+            let mut pairs: Vec<_> = map.iter().collect();
+            pairs.sort_by(|(a, _), (b, _)| a.cmp(b));
+            pairs
+                .into_iter()
+                .map(|(k, v)| format!("{k}={v}"))
+                .collect::<Vec<_>>()
+                .join(", ")
+        }
+    };
+    println!("  env: {env_display}");
+    if let Some(timeout) = server.startup_timeout_ms {
+        println!("  startup_timeout_ms: {timeout}");
+    }
+    println!("  remove: codex mcp remove {}", get_args.name);
+
+    Ok(())
+}
+
+fn parse_env_pair(raw: &str) -> Result<(String, String), String> {
+    let mut parts = raw.splitn(2, '=');
+    let key = parts
+        .next()
+        .map(str::trim)
+        .filter(|s| !s.is_empty())
+        .ok_or_else(|| "environment entries must be in KEY=VALUE form".to_string())?;
+    let value = parts
+        .next()
+        .map(str::to_string)
+        .ok_or_else(|| "environment entries must be in KEY=VALUE form".to_string())?;
+
+    Ok((key.to_string(), value))
+}
+
+fn validate_server_name(name: &str) -> Result<()> {
+    let is_valid = !name.is_empty()
+        && name
+            .chars()
+            .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_');
+
+    if is_valid {
+        Ok(())
+    } else {
+        bail!("invalid server name '{name}' (use letters, numbers, '-', '_')");
+    }
+}

codex-rs/cli/tests/mcp_add_remove.rs

@@ -0,0 +1,86 @@
+use std::path::Path;
+
+use anyhow::Result;
+use codex_core::config::load_global_mcp_servers;
+use predicates::str::contains;
+use pretty_assertions::assert_eq;
+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_server_updates_global_config() -> Result<()> {
+    let codex_home = TempDir::new()?;
+
+    let mut add_cmd = codex_command(codex_home.path())?;
+    add_cmd
+        .args(["mcp", "add", "docs", "--", "echo", "hello"])
+        .assert()
+        .success()
+        .stdout(contains("Added global MCP server 'docs'."));
+
+    let servers = load_global_mcp_servers(codex_home.path())?;
+    assert_eq!(servers.len(), 1);
+    let docs = servers.get("docs").expect("server should exist");
+    assert_eq!(docs.command, "echo");
+    assert_eq!(docs.args, vec!["hello".to_string()]);
+    assert!(docs.env.is_none());
+
+    let mut remove_cmd = codex_command(codex_home.path())?;
+    remove_cmd
+        .args(["mcp", "remove", "docs"])
+        .assert()
+        .success()
+        .stdout(contains("Removed global MCP server 'docs'."));
+
+    let servers = load_global_mcp_servers(codex_home.path())?;
+    assert!(servers.is_empty());
+
+    let mut remove_again_cmd = codex_command(codex_home.path())?;
+    remove_again_cmd
+        .args(["mcp", "remove", "docs"])
+        .assert()
+        .success()
+        .stdout(contains("No MCP server named 'docs' found."));
+
+    let servers = load_global_mcp_servers(codex_home.path())?;
+    assert!(servers.is_empty());
+
+    Ok(())
+}
+
+#[test]
+fn add_with_env_preserves_key_order_and_values() -> Result<()> {
+    let codex_home = TempDir::new()?;
+
+    let mut add_cmd = codex_command(codex_home.path())?;
+    add_cmd
+        .args([
+            "mcp",
+            "add",
+            "envy",
+            "--env",
+            "FOO=bar",
+            "--env",
+            "ALPHA=beta",
+            "--",
+            "python",
+            "server.py",
+        ])
+        .assert()
+        .success();
+
+    let servers = load_global_mcp_servers(codex_home.path())?;
+    let envy = servers.get("envy").expect("server should exist");
+    let env = envy.env.as_ref().expect("env should be present");
+
+    assert_eq!(env.len(), 2);
+    assert_eq!(env.get("FOO"), Some(&"bar".to_string()));
+    assert_eq!(env.get("ALPHA"), Some(&"beta".to_string()));
+
+    Ok(())
+}

codex-rs/cli/tests/mcp_list.rs

@@ -0,0 +1,106 @@
+use std::path::Path;
+
+use anyhow::Result;
+use predicates::str::contains;
+use pretty_assertions::assert_eq;
+use serde_json::Value as JsonValue;
+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 list_shows_empty_state() -> Result<()> {
+    let codex_home = TempDir::new()?;
+
+    let mut cmd = codex_command(codex_home.path())?;
+    let output = cmd.args(["mcp", "list"]).output()?;
+    assert!(output.status.success());
+    let stdout = String::from_utf8(output.stdout)?;
+    assert!(stdout.contains("No MCP servers configured yet."));
+
+    Ok(())
+}
+
+#[test]
+fn list_and_get_render_expected_output() -> Result<()> {
+    let codex_home = TempDir::new()?;
+
+    let mut add = codex_command(codex_home.path())?;
+    add.args([
+        "mcp",
+        "add",
+        "docs",
+        "--env",
+        "TOKEN=secret",
+        "--",
+        "docs-server",
+        "--port",
+        "4000",
+    ])
+    .assert()
+    .success();
+
+    let mut list_cmd = codex_command(codex_home.path())?;
+    let list_output = list_cmd.args(["mcp", "list"]).output()?;
+    assert!(list_output.status.success());
+    let stdout = String::from_utf8(list_output.stdout)?;
+    assert!(stdout.contains("Name"));
+    assert!(stdout.contains("docs"));
+    assert!(stdout.contains("docs-server"));
+    assert!(stdout.contains("TOKEN=secret"));
+
+    let mut list_json_cmd = codex_command(codex_home.path())?;
+    let json_output = list_json_cmd.args(["mcp", "list", "--json"]).output()?;
+    assert!(json_output.status.success());
+    let stdout = String::from_utf8(json_output.stdout)?;
+    let parsed: JsonValue = serde_json::from_str(&stdout)?;
+    let array = parsed.as_array().expect("expected array");
+    assert_eq!(array.len(), 1);
+    let entry = &array[0];
+    assert_eq!(entry.get("name"), Some(&JsonValue::String("docs".into())));
+    assert_eq!(
+        entry.get("command"),
+        Some(&JsonValue::String("docs-server".into()))
+    );
+
+    let args = entry
+        .get("args")
+        .and_then(|v| v.as_array())
+        .expect("args array");
+    assert_eq!(
+        args,
+        &vec![
+            JsonValue::String("--port".into()),
+            JsonValue::String("4000".into())
+        ]
+    );
+
+    let env = entry
+        .get("env")
+        .and_then(|v| v.as_object())
+        .expect("env map");
+    assert_eq!(env.get("TOKEN"), Some(&JsonValue::String("secret".into())));
+
+    let mut get_cmd = codex_command(codex_home.path())?;
+    let get_output = get_cmd.args(["mcp", "get", "docs"]).output()?;
+    assert!(get_output.status.success());
+    let stdout = String::from_utf8(get_output.stdout)?;
+    assert!(stdout.contains("docs"));
+    assert!(stdout.contains("command: docs-server"));
+    assert!(stdout.contains("args: --port 4000"));
+    assert!(stdout.contains("env: TOKEN=secret"));
+    assert!(stdout.contains("remove: codex mcp remove docs"));
+
+    let mut get_json_cmd = codex_command(codex_home.path())?;
+    get_json_cmd
+        .args(["mcp", "get", "docs", "--json"])
+        .assert()
+        .success()
+        .stdout(contains("\"name\": \"docs\""));
+
+    Ok(())
+}