{"record":{"id":"3be2b451a745f542","repo":"sipeed/picoclaw","slug":"header-can-only-be-used-with-http-or-sse-transpo","errorCode":null,"errorMessage":"--header can only be used with http or sse transport","messagePattern":"--header can only be used with http or sse transport","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/picoclaw/internal/mcp/add.go","lineNumber":222,"sourceCode":"\t\t\treturn config.MCPServerConfig{}, fmt.Errorf(\"--env can only be used with stdio transport\")\n\t\t}\n\t\tif strings.TrimSpace(opts.EnvFile) != \"\" {\n\t\t\treturn config.MCPServerConfig{}, fmt.Errorf(\"--env-file can only be used with stdio transport\")\n\t\t}\n\t\tif len(args) > 0 {\n\t\t\treturn config.MCPServerConfig{}, fmt.Errorf(\"%s transport does not accept command arguments\", transport)\n\t\t}\n\t\tparsedURL, err := url.ParseRequestURI(target)\n\t\tif err != nil || parsedURL.Scheme == \"\" || parsedURL.Host == \"\" {\n\t\t\treturn config.MCPServerConfig{}, fmt.Errorf(\"invalid MCP URL %q\", target)\n\t\t}\n\t\tserver.URL = target\n\t\tserver.Headers = headers\n\t\treturn server, nil\n\t}\n\n\tif len(headers) > 0 {\n\t\treturn config.MCPServerConfig{}, fmt.Errorf(\"--header can only be used with http or sse transport\")\n\t}\n\n\tif looksLikeRemoteURL(target) {\n\t\treturn config.MCPServerConfig{}, fmt.Errorf(\n\t\t\t\"target %q looks like a remote MCP URL, but transport is %q. Use --transport http or --transport sse\",\n\t\t\ttarget,\n\t\t\ttransport,\n\t\t)\n\t}\n\n\tcommand := target\n\tcommandArgs := append([]string(nil), args...)\n\n\tif err := validateLocalCommandPath(target); err != nil {\n\t\treturn config.MCPServerConfig{}, err\n\t}\n\tif isLocalCommandPath(command) {\n\t\tcommand = expandHomePath(command)","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/sipeed/picoclaw/blob/49183d7e8daed0dba89ddbb6fcb60089401d9680/cmd/picoclaw/internal/mcp/add.go#L204-L240","documentation":"Headers are only meaningful for http/sse servers; buildServerConfig rejects any parsed --header/-H value once transport falls through to the stdio branch (add.go:221-223). Since --transport defaults to stdio, supplying a header without explicitly selecting a remote transport always fails. The guard prevents silently dropping auth headers a stdio child process would never use.","triggerScenarios":"`picoclaw mcp add s mycmd -H \"Authorization: Bearer x\"` with no --transport flag (defaults to stdio).","commonSituations":"Adding an API-key header out of habit while configuring a local stdio server; not noticing that --transport defaults to stdio; migrating a remote server entry but forgetting the -t flag.","solutions":["If the target is a URL, add --transport http (or streamable-http, which normalizes to http) or --transport sse","If the target really is a stdio command, remove the -H/--header flags"],"exampleFix":"# before\npicoclaw mcp add s ./server -H \"X-Key: v\"\n# after\npicoclaw mcp add s https://example.com/mcp --transport http -H \"X-Key: v\"","handlingStrategy":"validation","validationCode":"# validate flag/transport compatibility before invoking\nif [ ${#HEADERS[@]} -gt 0 ] && [ \"$TRANSPORT\" = \"stdio\" ]; then\n  echo \"--header requires --transport http or sse\" >&2; exit 2\nfi\npicoclaw mcp add \"$name\" \"$target\" --transport \"$TRANSPORT\" \"${HEADERS[@]}\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Remember --transport defaults to stdio; state it explicitly whenever using -H","Treat -H/-e as transport-scoped flags: headers→http/sse, env→stdio"],"tags":["cli","mcp","flags","transport"],"backgroundTag":null,"analyzedSha":"49183d7e8daed0dba89ddbb6fcb60089401d9680","analyzedAt":"2026-08-15T21:55:41.315Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}