googleapis/mcp-toolbox · error

base URL must include scheme and host

Error message

base URL must include scheme and host

What it means

After parsing, getURL requires the base URL to have both a scheme and a host so ResolveReference can build an absolute request URL. A base like "api.example.com" (no scheme) or "/api" (no host) triggers this error at Invoke time.

Source

Thrown at internal/tools/http/http.go:194

		},
	}

	templ, err := template.New("url").Funcs(funcMap).Parse(path)
	if err != nil {
		return "", fmt.Errorf("error parsing URL: %s", err)
	}
	var templatedPath bytes.Buffer
	err = templ.Execute(&templatedPath, pathParamsMap)
	if err != nil {
		return "", fmt.Errorf("error replacing pathParams: %s", err)
	}

	baseParsedURL, err := url.Parse(baseURL)
	if err != nil {
		return "", fmt.Errorf("error parsing base URL: %s", err)
	}
	if baseParsedURL.Scheme == "" || baseParsedURL.Host == "" {
		return "", fmt.Errorf("base URL must include scheme and host")
	}

	relativePath := templatedPath.String()
	relParsedURL, err := url.Parse(relativePath)
	if err != nil {
		return "", fmt.Errorf("error parsing URL path: %s", err)
	}
	if relParsedURL.Scheme != "" || relParsedURL.Host != "" || relParsedURL.User != nil {
		return "", fmt.Errorf("path must be relative and cannot override base host")
	}

	// Reject dot segments before resolution
	for _, segment := range strings.Split(relParsedURL.Path, "/") {
		if segment == ".." {
			return "", fmt.Errorf("path cannot contain dot segments (..)")
		}
	}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Prefix the source's baseUrl with its scheme, e.g. "https://api.example.com".
2. Ensure the baseUrl includes a host, not just a path.
3. Validate baseUrl scheme/host at source initialization to fail fast at startup rather than at Invoke.

Example fix

# before
baseUrl: "api.example.com/v1"
# after
baseUrl: "https://api.example.com/v1"

// Require absolute URL for the source's baseUrl
u, err := url.Parse(baseURL)
if err != nil || u.Scheme == "" || u.Host == "" {
    return fmt.Errorf("baseUrl must be absolute, e.g. https://api.example.com; got %q", baseURL)
}

When it happens

Trigger: The http source's baseUrl is set to a scheme-less value like "localhost:8080/api" or a relative path like "/v1", so baseParsedURL.Scheme == "" or Host == "".

Common situations: Omitting "https://" from baseUrl in tools.yaml; using a relative base intended to be completed later; documentation examples copied without the scheme.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• error parsing base URL: %s
• invalid auth URL
• error creating request: %w
• failed to create request: %w
• description is required for tool %q

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/1576216a3626f628. Report an issue: GitHub.