What causes "%s transport does not accept command arguments" in sipeed/picoclaw?

Keep the http/sse form to exactly ` `

%s transport does not accept command arguments

Error message

%s transport does not accept command arguments

What it means

http/sse servers are URL-only in buildServerConfig: after validating the URL (url.ParseRequestURI plus scheme/host checks), any leftover command arguments are rejected. Args reach this check as positionals beyond <name> <url> or as serverArgs captured once two positionals exist.

Source

Thrown at cmd/picoclaw/internal/mcp/add.go:210

		return config.MCPServerConfig{}, err
	}

	server := config.MCPServerConfig{
		Enabled:  true,
		Type:     transport,
		Deferred: opts.Deferred,
	}

	switch transport {
	case "http", "sse":
		if len(env) > 0 {
			return config.MCPServerConfig{}, fmt.Errorf("--env can only be used with stdio transport")
		}
		if strings.TrimSpace(opts.EnvFile) != "" {
			return config.MCPServerConfig{}, fmt.Errorf("--env-file can only be used with stdio transport")
		}
		if len(args) > 0 {
			return config.MCPServerConfig{}, fmt.Errorf("%s transport does not accept command arguments", transport)
		}
		parsedURL, err := url.ParseRequestURI(target)
		if err != nil || parsedURL.Scheme == "" || parsedURL.Host == "" {
			return config.MCPServerConfig{}, fmt.Errorf("invalid MCP URL %q", target)
		}
		server.URL = target
		server.Headers = headers
		return server, nil
	}

	if len(headers) > 0 {
		return config.MCPServerConfig{}, fmt.Errorf("--header can only be used with http or sse transport")
	}

	if looksLikeRemoteURL(target) {
		return config.MCPServerConfig{}, fmt.Errorf(
			"target %q looks like a remote MCP URL, but transport is %q. Use --transport http or --transport sse",
			target,

View on GitHub (pinned to 49183d7e8d)

Solutions

Keep the http/sse form to exactly `<name> <url>`
Pass headers with --header/-H, e.g. `-H 'X-Api-Key: key'`
If you need a command with arguments, use stdio transport (default, or -t stdio)

Example fix

# before
picoclaw mcp add api https://example.com/mcp -t http --api-key secret
# after
picoclaw mcp add api https://example.com/mcp -t http -H 'X-Api-Key: secret'

Defensive patterns

Strategy: validation

Validate before calling

if [ "$TRANSPORT" = http ] || [ "$TRANSPORT" = sse ]; then [ $# -eq 2 ] || { echo "http/sse takes only <name> <url>"; exit 2; }; fi

Prevention

For http/sse, stop the command line after <name> <url>
Send options as -H headers, not bare arguments
Switch to stdio when the server needs a command line

When it happens

Trigger: `picoclaw mcp add name https://host/mcp extra-arg --transport http`; or flags after the URL that the parser forwards as server arguments.

Common situations: Pasting a stdio command line and only changing the transport to http; trying to pass an API key as a bare positional instead of -H.

Related errors

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