What causes "MCP server ${server.name} requires a valid HTTP(S) URL." in sipeed/picoclaw?

Use a full http:// or https:// URL including scheme and host, e.g. https://mcp.example.com/sse

MCP server ${server.name} requires a valid HTTP(S) URL.

Error message

MCP server ${server.name} requires a valid HTTP(S) URL.

What it means

Validation error thrown in handleSave (web/frontend/src/components/config/config-page.tsx:482) when an enabled remote MCP server's URL either fails to parse via new URL() or parses with a protocol other than http: or https: (the internal 'invalid protocol' throw is swallowed and re-raised as this message). Only enabled remote servers are validated.

Source

Thrown at web/frontend/src/components/config/config-page.tsx:482

            const baselineServer = baselineServersByName.get(server.name)
            const shouldValidateServer = server.enabled

            if (server.type !== "stdio") {
              if (shouldValidateServer && server.url === "") {
                throw new Error(`MCP server ${server.name} requires a URL.`)
              }

              if (shouldValidateServer) {
                try {
                  const parsedURL = new URL(server.url)
                  if (
                    parsedURL.protocol !== "http:" &&
                    parsedURL.protocol !== "https:"
                  ) {
                    throw new Error("invalid protocol")
                  }
                } catch {
                  throw new Error(
                    `MCP server ${server.name} requires a valid HTTP(S) URL.`,
                  )
                }
              }

              const baselineHeaders = baselineServer
                ? parseJSONObjectField(
                    baselineServer.headersText,
                    `Saved MCP server ${server.name} headers`,
                  )
                : {}

              return [
                server.name,
                {
                  ...deferredPatch,
                  enabled: server.enabled,
                  type: server.type,

View on GitHub (pinned to 49183d7e8d)

Solutions

Use a full http:// or https:// URL including scheme and host, e.g. https://mcp.example.com/sse
Convert ws://host to http://host and wss://host to https://host — the MCP HTTP transport upgrades internally
Double-check for typos in the scheme (http//, http:/) and stray whitespace after trimming

Example fix

// before
ws://mcp.example.com/sse

// after
https://mcp.example.com/sse

Defensive patterns

Strategy: validation

Validate before calling

function isHTTPUrl(value: string): boolean {
  try {
    const u = new URL(value.trim())
    return u.protocol === "http:" || u.protocol === "https:"
  } catch {
    return false
  }
}

if (form.mcpServers.some((s) => s.type !== "stdio" && s.enabled && !isHTTPUrl(s.url))) {
  setFieldError("Remote MCP servers require a valid http(s) URL.")
  return
}

Type guard

function parseHTTPUrl(value: string): URL | null {
  try {
    const u = new URL(value.trim())
    return u.protocol === "http:" || u.protocol === "https:" ? u : null
  } catch {
    return null
  }
}

Try / catch

try {
  await handleSave()
} catch (err) {
  if (err instanceof Error) setError(err.message)
}

Prevention

Validate the URL field on blur and show a scheme hint (https://)
Auto-prepend https:// when the user types a bare host
Translate ws://→http:// and wss://→https:// at input time if providers document WebSocket endpoints

When it happens

Trigger: Entering ws://server/sse or wss:// (WebSocket schemes), file:///path, a bare hostname like mcp.example.com without a scheme (unparseable by new URL), or a URL with a typo like http//example.com.

Common situations: Provider docs advertise a ws:// transport URL; user pastes just the host without https://; user pastes a URL with spaces or non-ASCII characters; confusion between MCP stdio servers and SSE endpoints.

Related errors

AI-assisted analysis of sipeed/picoclaw@49183d7e8d (2026-08-15). Data as JSON: /api/errors/ce5976be37218870. Report an issue: GitHub.