Invalid URL '{url}'. Server URLs must start with http:// or

Error message

Invalid URL '{url}'. Server URLs must start with http:// or https://.

What it means

When adding an HTTP/SSE MCP server, the URL argument must start with http:// or https://. Anything else (bare host, file path, ws://, etc.) is rejected with this message so a malformed endpoint never reaches the HTTP client.

Source

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

                    env: (!env.is_empty()).then_some(env),
                    cwd: None,
                },
                warnings,
            })
        }
        McpTransport::Http | McpTransport::Sse => {
            let label = if transport == McpTransport::Sse {
                "sse"
            } 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."
                ));
            }

View on GitHub (pinned to bc7f02eddd)

Solutions

Prefix the URL with https:// (or http:// for plain-HTTP endpoints).
Verify the full endpoint URL from the MCP server provider's docs.
Use --transport stdio if the server is actually a local command, not an HTTP endpoint.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

fn is_http_url(s: &str) -> bool { s.starts_with("http://") || s.starts_with("https://") }
assert!(is_http_url(url), "URL must start with http:// or https://");

Type guard

fn is_http_url(s: &str) -> bool { s.starts_with("http://") || s.starts_with("https://") }

Prevention

Always include the scheme in server URLs.
Normalize URLs in scripts to add https:// when missing.
Use stdio transport for local commands instead of file:// or path URLs.

When it happens

Trigger: `grok mcp add <name> --transport http acme.example.com/mcp` or a URL using an unsupported scheme like `grpc://` or a local path.

Common situations: Omitting the scheme out of habit (browsers auto-add https), copying an internal `http://` URL but trimming the prefix, using ws:// or localhost:path forms from other tools' configs.

Related errors

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