unslothai/unsloth · warning · HTTPException

MCP server address must start with http:// or https:// (for

Error message

MCP server address must start with http:// or https:// (for example https://example.com/mcp).

What it means

400 raised when the value has no http/https scheme and no whitespace (so it doesn't look like a command) — e.g. a bare host, a scheme-less URL, or a typo like 'htp://'. urlparse puts such strings in the path, the scheme check fails, and the user is pointed at the required http:// or https:// prefix.

Source

Thrown at studio/backend/routes/mcp_servers.py:103

                status_code = 400,
                detail = "Enter an http(s):// URL, or a local command whose "
                "first token is an executable (not a URL).",
            )
        return trimmed
    parsed = urlparse(trimmed)
    if parsed.scheme not in ("http", "https"):
        if _looks_like_command(trimmed):
            detail = (
                "Local commands aren't enabled on this server. To allow them, "
                "set UNSLOTH_STUDIO_ALLOW_STDIO_MCP=1 and restart Unsloth, or use "
                "an http:// or https:// URL instead."
            )
        else:
            detail = (
                "MCP server address must start with http:// or https:// "
                "(for example https://example.com/mcp)."
            )
        raise HTTPException(status_code = 400, detail = detail)
    if not parsed.netloc:
        raise HTTPException(status_code = 400, detail = "url is missing a host")
    return trimmed


def _normalize_headers(headers: dict[str, str] | None) -> dict[str, str] | None:
    """Trim header names, drop empties, coerce values to str; None if empty."""
    if not headers:
        return None
    out: dict[str, str] = {}
    for raw_key, value in headers.items():
        key = str(raw_key).strip()
        if key:
            out[key] = str(value)
    return out or None


def _row_to_response(row: dict) -> McpServerResponse:

View on GitHub (pinned to 203007d190)

Solutions

1. Prefix the address with http:// or https:// (e.g. 'https://example.com/mcp').
2. For local servers use 'http://127.0.0.1:PORT/mcp', not '127.0.0.1:PORT'.
3. Strip accidental leading whitespace/characters that break scheme parsing.

Example fix

# before
{'url': 'example.com/mcp'}  # -> 400, missing scheme

# after
{'url': 'https://example.com/mcp'}

function normalizeMcpUrl(raw) {
  const v = (raw ?? '').trim();
  if (!/^https:\/\/|http:\/\//.test(v)) return 'https://' + v.replace(/^\/+/, '');
  return v;
}

const isHttpUrl = (v) => /^https?:\/\/[^\s]+$/i.test(v.trim());

When it happens

Trigger: POST/PUT an MCP server with url values like 'example.com/mcp', 'localhost:8080', or 'ftp://example.com' — single-token values that aren't commands and aren't http(s).

Common situations: Users omitting the scheme out of browser-address-bar habit, or configs migrated from tools that accept bare hosts.

Related errors

• url must not be empty
• Enter an http(s):// URL, or a local command whose first toke
• url is missing a host
• command must not be empty
• is_enabled must be true or false

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/546317a4859be50b. Report an issue: GitHub.