openai/codex · error · anyhow::Error

command is required

Error message

command is required

What it means

For `codex mcp add <name>` with the stdio transport, run_add takes stdio.command (a Vec<String> built from --command) and requires a first element to use as the program. An empty command list bails with `command is required` before any config is written.

Source

Thrown at codex-rs/cli/src/mcp_cmd.rs:360

        name,
        transport_args,
    } = add_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)
        .await
        .with_context(|| format!("failed to load MCP servers from {}", codex_home.display()))?;

    let (transport, oauth_client_id, client_registration, oauth_resource) = match transport_args {
        AddMcpTransportArgs {
            stdio: Some(stdio), ..
        } => {
            let mut command_parts = stdio.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 stdio.env.is_empty() {
                None
            } else {
                Some(stdio.env.into_iter().collect::<HashMap<_, _>>())
            };
            (
                McpServerTransportConfig::Stdio {
                    command: command_bin,
                    args: command_args,
                    env: env_map,
                    env_vars: Vec::new(),
                    cwd: None,
                },
                None,
                McpOAuthClientRegistration::Auto,
                None,

View on GitHub (pinned to 339751715c)

Solutions

1. Pass a program plus its args: `codex mcp add fs --command npx -y @modelcontextprotocol/server-filesystem /tmp`.
2. Fail fast on unset variables: `set -u` plus `: "${BIN:?BIN must be set}"` before invoking codex.
3. Verify the program resolves: `command -v "$BIN"`.

Example fix

# before
codex mcp add fs --command            # flag with no program
codex mcp add fs --command $BIN       # $BIN unset -> empty command list
# after
codex mcp add fs --command npx -y @modelcontextprotocol/server-filesystem /tmp

add_mcp_stdio() {
  local name="$1"; shift
  if [ $# -eq 0 ] || [ -z "$1" ]; then
    echo 'command is required: program name first, then args' >&2; return 2
  fi
  command -v "$1" >/dev/null 2>&1 || echo "warn: '$1' not found on PATH" >&2
  codex mcp add "$name" --command "$@"
}

if ! codex mcp add fs --command "$@" 2>err.log; then
  grep -q 'command is required' err.log && { echo 'usage: --command <program> [args...]' >&2; exit 2; }
  exit 1
fi

When it happens

Trigger: `codex mcp add my-server --command` with no values following the flag, or a script expanding an unset variable into the command slot so the parsed list is empty (`--command $BIN` with BIN unset and word splitting dropping it).

Common situations: Wrapper scripts building the command from variables that came back empty; CI jobs injecting the program name from a missing env var; copy-paste that kept the flag but dropped the program.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• exactly one of --command or --url must be provided
• No MCP server named '{name}' found.
• `--remote-auth-token-env` is only supported for interactive
• `--strict-config` is not supported for `codex {subcommand}`
• environment variable `{env_var_name}` is not set

AI-assisted analysis of openai/codex@339751715c (2026-08-25). Data as JSON: /api/errors/0f0c17381eb2f8af. Report an issue: GitHub.