What causes "MCP server ${server.name} requires a URL." in sipeed/picoclaw?

Enter the server's HTTP(S) endpoint URL, e.g. https://mcp.example.com/sse

MCP server ${server.name} requires a URL.

Error message

MCP server ${server.name} requires a URL.

What it means

Validation error thrown in handleSave (web/frontend/src/components/config/config-page.tsx:469) while building the MCP servers patch: a server of type other than 'stdio' (i.e. an HTTP/SSE remote server) that is enabled has an empty URL after trimming. Disabled (enabled=false) servers skip this check via shouldValidateServer, so only active remote servers must have a URL.

Source

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

          const baselineServersByName = new Map(
            baseline.mcpServers
              .map((server) => ({
                ...server,
                name: server.name.trim(),
              }))
              .filter((server) => server.name !== "")
              .map((server) => [server.name, server] as const),
          )

          const upsertServerEntries = normalizedServers.map((server) => {
            const deferredPatch = { deferred: server.deferredOverride }
            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.`,
                  )
                }
              }

View on GitHub (pinned to 49183d7e8d)

Solutions

Enter the server's HTTP(S) endpoint URL, e.g. https://mcp.example.com/sse
If the server is not ready yet, toggle it to disabled — disabled remote servers are exempt from URL validation
If the server is actually a local process, switch its type to 'stdio' and fill the command instead

Defensive patterns

Strategy: validation

Validate before calling

const needsURL = (s: McpServerForm) => s.type !== "stdio" && s.enabled
if (form.mcpServers.some((s) => needsURL(s) && s.url.trim() === "")) {
  setFieldError("Enabled remote MCP servers require a URL.")
  return
}

Try / catch

try {
  await handleSave()
} catch (err) {
  if (err instanceof Error) setError(err.message) // message names the server
}

Prevention

Mark the URL field required (visually) for enabled remote server rows
Disable validation-exempt state by reminding users disabled servers are not started
Trim the URL on blur so whitespace-only values are visibly empty

When it happens

Trigger: Adding an enabled remote MCP server, filling in its name but leaving the URL field empty, then saving; also when a saved remote server's URL was cleared in the UI.

Common situations: User fills name first intending to paste the URL later and forgets; URL field contains only spaces; user thinks command applies to remote servers too.

Related errors

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