xai-org/grok-build · error

--env can only be used with stdio servers.

Error message

--env can only be used with stdio servers.

What it means

The `--env` flag configures environment variables for locally spawned stdio MCP server processes. When the transport is HTTP or SSE there is no child process to receive them, so the CLI rejects `--env` with this message.

Source

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

            } else {
                "http"
            };
            let Some(url) = source else {
                bail!(
                    "A URL is required for {label} servers. Usage: grok mcp add --transport {label} <name> <url>"
                );
            };
            if !url.starts_with("http://") && !url.starts_with("https://") {
                bail!("Invalid URL '{url}'. Server URLs must start with http:// or https://.");
            }
            if !server_args.is_empty() {
                bail!(
                    "Unexpected arguments after the URL: '{}'. HTTP and SSE servers take a single URL.",
                    server_args.join(" ")
                );
            }
            if !args.env.is_empty() {
                bail!("--env can only be used with stdio servers.");
            }
            let headers = parse_headers(&args.header)?;

            let mut warnings = Vec::new();
            if inferred_http {
                warnings.push(format!(
                    "No --transport given; '{url}' starts with http(s)://, adding as an HTTP server. Use --transport sse for an SSE server, or --transport stdio to force a stdio command."
                ));
            }

            Ok(ResolvedAdd {
                kind: transport,
                transport: McpServerTransportConfig::StreamableHttp {
                    url: url.to_string(),
                    transport_type: (transport == McpTransport::Sse).then(|| "sse".to_string()),
                    bearer_token_env_var: None,
                    headers: (!headers.is_empty()).then_some(headers),
                    oauth_client_id: None,

View on GitHub (pinned to bc7f02eddd)

Solutions

1. Remove the -e/--env flags for HTTP/SSE servers.
2. Pass authentication or configuration via --header 'Name: value' instead (HTTP headers).
3. Keep --env only with stdio servers where the process is launched locally.

Example fix

// before
grok mcp add acme --transport http https://acme.example.com/mcp -e API_KEY=abc
// after
grok mcp add acme --transport http https://acme.example.com/mcp --header 'Authorization: Bearer abc'

if transport_is_http_or_sse {
    assert!(env_flags.is_empty(), "--env is only valid for stdio servers; use --header for HTTP config");
}

When it happens

Trigger: `grok mcp add <name> --transport http <url> -e KEY=value` (or --transport sse) — any non-empty env list combined with a remote transport.

Common situations: Reusing a shared add-command template that always appends -e flags; attempting to send credentials to a remote server that should instead use headers; migrating a stdio entry to http without cleaning flags.

Related errors

• Invalid command '{command}': it looks like an environment va
• Invalid environment variable format: '{pair}'. Environment v
• --header can only be used with HTTP or SSE servers.
• A URL is required for {label} servers. Usage: grok mcp add -
• Invalid URL '{url}'. Server URLs must start with http:// or

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