sipeed/picoclaw · error

usage: picoclaw mcp add [flags] <name> <command-or-url> [arg

Error message

usage: picoclaw mcp add [flags] <name> <command-or-url> [args...] or picoclaw mcp add [flags] <name> -- <command> [args...]

What it means

When the mcp add argument list contains `--`, everything after it is treated as the explicit server command (explicitCommand). This error fires when explicitCommand is non-empty but the positional count before `--` is not exactly 1 - the parser expects exactly the server <name> there, nothing more, nothing less.

Source

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

		case arg == "--header" || arg == "-H":
			if i+1 >= len(args) {
				return addOptions{}, "", "", nil, false, fmt.Errorf("missing value for %s", arg)
			}
			i++
			opts.Headers = append(opts.Headers, args[i])
		case strings.HasPrefix(arg, "--header="):
			opts.Headers = append(opts.Headers, strings.TrimPrefix(arg, "--header="))
		case strings.HasPrefix(arg, "-") && len(positional) >= 2:
			serverArgs = append(serverArgs, args[i:]...)
			i = len(args)
		default:
			positional = append(positional, arg)
		}
	}

	if len(explicitCommand) > 0 {
		if len(positional) != 1 {
			return addOptions{}, "", "", nil, false, fmt.Errorf(
				"usage: picoclaw mcp add [flags] <name> <command-or-url> [args...] or picoclaw mcp add [flags] <name> -- <command> [args...]",
			)
		}
		if len(explicitCommand) == 0 {
			return addOptions{}, "", "", nil, false, fmt.Errorf("missing stdio command after --")
		}
		return opts, positional[0], explicitCommand[0], explicitCommand[1:], false, nil
	}

	if len(positional) < 2 {
		return addOptions{}, "", "", nil, false, fmt.Errorf(
			"usage: picoclaw mcp add [flags] <name> <command-or-url> [args...] or picoclaw mcp add [flags] <name> -- <command> [args...]",
		)
	}

	targetArgs := make([]string, 0, len(positional)-2+len(serverArgs))
	targetArgs = append(targetArgs, positional[2:]...)
	targetArgs = append(targetArgs, serverArgs...)

View on GitHub (pinned to 49183d7e8d)

Solutions

1. Use the exact layout: `picoclaw mcp add [flags] <name> -- <command> [args...]`
2. Remove the extra positional (usually the command-or-url) before `--`
3. Or drop `--` and use the plain form `picoclaw mcp add <name> <command-or-url> [args...]`

Example fix

# before
picoclaw mcp add fs npx -- -y @mcp/fs
# after
picoclaw mcp add fs -- npx -y @mcp/fs

# exactly one positional before --
set -- name cmd arg1   # wrong
set -- name -- cmd arg1 # right
picoclaw mcp add "$@"

When it happens

Trigger: `picoclaw mcp add name npx -- -y server` (2 positionals before --, e.g. name plus a command-or-url) or `picoclaw mcp add -- cmd arg` (0 positionals).

Common situations: Leaving the old command-or-url in place after adding `--`; forgetting the server name; assuming `--` can follow any argument layout.

Related errors

• missing value for %s
• %s transport does not accept command arguments
• either --every or --cron must be specified
• the --no-truncate option can only be used in conjunction wit
• failed to confirm overwrite: %w

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