{"record":{"id":"6ccb4641fa1cea6e","repo":"xai-org/grok-build","slug":"header-can-only-be-used-with-http-or-sse-servers","errorCode":null,"errorMessage":"--header can only be used with HTTP or SSE servers.","messagePattern":"--header can only be used with HTTP or SSE servers\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/codegen/xai-grok-pager/src/mcp_cmd.rs","lineNumber":329,"sourceCode":"    } else {\n        &args.args\n    };\n    // Clap's \"source\" group guarantees at most one of these is set.\n    let source = args\n        .command_or_url\n        .as_deref()\n        .or(args.command.as_deref())\n        .or(args.url.as_deref());\n\n    match transport {\n        McpTransport::Stdio => {\n            let Some(command) = source else {\n                bail!(\n                    \"A command is required for stdio servers. Usage: grok mcp add <name> -- <command> [args...]\"\n                );\n            };\n            if !args.header.is_empty() {\n                bail!(\"--header can only be used with HTTP or SSE servers.\");\n            }\n            // A KEY=value command means an env pair leaked out of -e, which takes one pair per flag (the old --env was greedy)\n            if looks_like_env_pair(command) {\n                let pairs: Vec<String> = args\n                    .env\n                    .iter()\n                    .map(String::as_str)\n                    .chain([command])\n                    .map(|pair| format!(\"-e {pair}\"))\n                    .collect();\n                bail!(\n                    \"Invalid command '{command}': it looks like an environment variable. Pass each variable as its own flag: {}\",\n                    pairs.join(\" \")\n                );\n            }\n            let env = parse_env_vars(&args.env)?;\n\n            let mut warnings = Vec::new();","sourceCodeStart":311,"sourceCodeEnd":347,"githubUrl":"https://github.com/xai-org/grok-build/blob/bc7f02eddd3d84085849dc19ed216f11c23b0571/crates/codegen/xai-grok-pager/src/mcp_cmd.rs#L311-L347","documentation":"This error is thrown by the `grok mcp add` command resolver when the `--header` flag is supplied but the resolved transport is a stdio server (no --transport given and the trailing command is not a URL). Headers only make sense for HTTP/SSE transports, so the CLI rejects the combination early with guidance. It is a usage/validation error, not a runtime failure.","triggerScenarios":"Running `grok mcp add <name> --header 'Name: value' -- <command> [args...]` where the transport resolves to stdio (source is a command, not an http/https URL and no --transport http/sse was passed).","commonSituations":"Developers copying an HTTP-server invocation and just swapping the command for a local stdio binary; scripts templating headers for all servers; misunderstanding that headers are ignored/unsupported for stdio MCP servers.","solutions":["Remove the --header flags since stdio servers cannot use HTTP headers.","Add --transport http or --transport sse and pass a URL instead of a command if the server is actually remote.","Move any auth configuration to env vars passed with -e KEY=value for the stdio process."],"exampleFix":"// before\ngrok mcp add fs --header 'Authorization: Bearer x' -- npx -y @modelcontextprotocol/server-fs /tmp\n// after\ngrok mcp add fs -- npx -y @modelcontextprotocol/server-fs /tmp","handlingStrategy":"validation","validationCode":"fn is_url(s: &str) -> bool { s.starts_with(\"http://\") || s.starts_with(\"https://\") }\nif !headers.is_empty() && !(transport_is_http_or_sse || command.map_or(false, is_url)) {\n    eprintln!(\"--header requires --transport http/sse (or a URL command)\");\n}","typeGuard":"fn is_remote_transport(t: &str) -> bool { matches!(t, \"http\" | \"sse\") }","tryCatchPattern":null,"preventionTips":["Only pass --header with --transport http or sse.","Match header flags to URL-based server entries.","Keep stdio server invocations to command + -e env flags."],"tags":["cli","mcp","validation","arguments"],"backgroundTag":"flag-not-valid-for-transport","analyzedSha":"bc7f02eddd3d84085849dc19ed216f11c23b0571","analyzedAt":"2026-08-31T04:59:42.031Z","schemaVersion":2},"datasetVersion":"2026-08-31T09:17:48.483Z"}