Invalid name '{name}'. Names can only contain letters, numbe

Error message

Invalid name '{name}'. Names can only contain letters, numbers, hyphens, and underscores.

What it means

Server names for `grok mcp add` are validated against a strict charset: ASCII letters, digits, hyphens, and underscores. Empty names or names containing spaces, dots, slashes, or other punctuation are rejected so the name is always safe as a config key/identifier.

Source

Thrown at crates/codegen/xai-grok-pager/src/mcp_cmd.rs:428

                    bearer_token_env_var: None,
                    headers: (!headers.is_empty()).then_some(headers),
                    oauth_client_id: None,
                    oauth_client_secret_env_var: None,
                    oauth_scopes: None,
                },
                warnings,
            })
        }
    }
}

fn validate_server_name(name: &str) -> Result<()> {
    if name.is_empty()
        || !name
            .chars()
            .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_')
    {
        bail!(
            "Invalid name '{name}'. Names can only contain letters, numbers, hyphens, and underscores."
        );
    }
    Ok(())
}

fn parse_env_vars(pairs: &[String]) -> Result<HashMap<String, String>> {
    let mut env = HashMap::new();
    for pair in pairs {
        match pair.split_once('=') {
            Some((key, value)) if !key.is_empty() => {
                env.insert(key.to_string(), value.to_string());
            }
            _ => bail!(
                "Invalid environment variable format: '{pair}'. Environment variables should be added as: -e KEY1=value1 -e KEY2=value2"
            ),
        }
    }

View on GitHub (pinned to bc7f02eddd)

Solutions

Rename using only letters, numbers, hyphens, and underscores (e.g. acme-dev).
Trim whitespace from the name argument in scripts.
Quote and normalize names in automation before passing them to grok mcp add.

Example fix

// before
grok mcp add "Acme MCP" --transport http https://acme.example.com/mcp
// after
grok mcp add acme-mcp --transport http https://acme.example.com/mcp

Defensive patterns

Strategy: validation

Validate before calling

fn valid_name(name: &str) -> bool {
    !name.is_empty() && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_')
}
assert!(valid_name(server_name));

Prevention

Use kebab-case or snake_case server names.
Trim and sanitize names in automation before invoking the CLI.
Avoid spaces, dots, and slashes in names.

When it happens

Trigger: `grok mcp add "My Server!" ...`, an empty name, or names with dots/colons/slashes (e.g. `acme.dev`, `corp/mcp`).

Common situations: Using display labels with spaces, DNS-style dotted names, copy-pasted names with trailing whitespace or unicode characters from docs or other tool configs.

Related errors

AI-assisted analysis of xai-org/grok-build@bc7f02eddd (2026-08-31). Data as JSON: /api/errors/5c4e0e8dd4c79ec2. Report an issue: GitHub.