What causes "url is required for http server" in siyuan-note/siyuan?

Open the MCP server settings and fill in the HTTP endpoint URL (e.g. https://example.com/mcp)

url is required for http server

Error message

url is required for http server

What it means

connectHTTP is used for HTTP (streamable) MCP servers and requires server.URL to be set, since it configures a StreamableClientTransport with that endpoint. If an HTTP-type MCP server is configured without a URL, the connection cannot even be attempted, so it returns this error immediately.

Solutions

Open the MCP server settings and fill in the HTTP endpoint URL (e.g. https://example.com/mcp)
If editing conf.json, set the url field of the affected server entry
Alternatively, if the server is actually a local process, switch its type to stdio and configure a command instead of a URL

Example fix

// before (conf)
{"name": "myserver", "type": "http", "url": ""}
// after
{"name": "myserver", "type": "http", "url": "https://example.com/mcp"}

Defensive patterns

Strategy: validation

Validate before calling

if server.Type == "http" && server.URL == "" {
    return errors.New("HTTP MCP server requires a URL")
}
if _, err := url.Parse(server.URL); err != nil {
    return fmt.Errorf("invalid URL: %w", err)
}

Prevention

Require the URL field in the settings form when transport type is HTTP
Validate the URL parses and uses http/https before saving
Switch to stdio type (with a command) for local process servers instead of leaving URL blank

When it happens

Trigger: connectServer dispatches to connectHTTP for a server with an HTTP transport type but conf.MCPServer.URL is empty (no endpoint configured).

Common situations: Creating an HTTP MCP server entry in the settings UI but leaving the endpoint field blank; a config migration/import that dropped the URL; toggling a server's type to HTTP without filling in the endpoint.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of siyuan-note/siyuan@9f775e8a12 (2026-09-19). Data as JSON: /api/errors/5c10c2f67d5ce2e1. Report an issue: GitHub.

Appendix: source

Thrown at kernel/mcp/client/mcp.go:618

	}
	sort.Slice(ret, func(i, j int) bool {
		left, right := strings.ToUpper(ret[i]), strings.ToUpper(ret[j])
		if left == right {
			return ret[i] < ret[j]
		}
		return left < right
	})
	return ret
}

// MCPEnvironmentVariables 返回当前内核环境变量名称和新服务默认允许继承的名称，不暴露变量值。
func MCPEnvironmentVariables() (names, defaults []string) {
	return environmentVariableNames(os.Environ(), runtime.GOOS), defaultMCPEnvironmentNames(runtime.GOOS)
}

func connectHTTP(ctx context.Context, client *mcp.Client, server conf.MCPServer, interactive bool) (*mcp.ClientSession, *exec.Cmd, *mcpOAuthHandler, error) {
	if server.URL == "" {
		return nil, nil, nil, fmt.Errorf("url is required for http server")
	}

	transport := newStreamableClientTransport(server)
	var oauthHandler *mcpOAuthHandler
	if !hasAuthorizationHeader(server.Headers) {
		oauthHandler = newMCPOAuthHandler(server, interactive)
		transport.OAuthHandler = oauthHandler
	}
	// 所有 MCP HTTP 出站请求统一带上 SiYuan UA，便于第三方 MCP server 识别客户端身份
	uaBase := httpclient.NewUserAgentRoundTripper(http.DefaultTransport)
	if len(server.Headers) > 0 {
		transport.HTTPClient = &http.Client{
			Transport: &headerRoundTripper{
				base:    uaBase,
				headers: server.Headers,
			},
		}
	} else {

View on GitHub (pinned to 9f775e8a12)