MCP HTTP headers helper exited with status {status}

Error message

MCP HTTP headers helper exited with status {status}

What it means

The headers helper ran to completion but wait() returned a non-zero exit status: whatever credential/provider command was configured refused to produce headers. The status code is included; stderr is discarded (Stdio::null), so the failure reason must be reproduced manually. This is the command failing, not the spawn machinery.

Source

Thrown at codex-rs/rmcp-client/src/http_headers.rs:336

        job,
    };
    let output = tokio::time::timeout(HELPER_TIMEOUT, async {
        let stdout = process
            .child
            .stdout
            .take()
            .ok_or_else(|| anyhow!("MCP HTTP headers helper stdout was unavailable"))?;
        let mut output = Vec::new();
        stdout
            .take((MAX_HELPER_OUTPUT_BYTES + 1) as u64)
            .read_to_end(&mut output)
            .await?;
        if output.len() > MAX_HELPER_OUTPUT_BYTES {
            return Err(anyhow!("MCP HTTP headers helper output exceeds 64 KiB"));
        }
        let status = process.child.wait().await?;
        if !status.success() {
            return Err(anyhow!(
                "MCP HTTP headers helper exited with status {status}"
            ));
        }
        Ok(output)
    })
    .await
    .map_err(|_| anyhow!("MCP HTTP headers helper timed out after 10 seconds"))??;

    parse_helper_output(output)
}

fn parse_helper_output(stdout: Vec<u8>) -> Result<HeaderMap> {
    let stdout = String::from_utf8(stdout)
        .map_err(|_| anyhow!("MCP HTTP headers helper wrote non-UTF-8 data"))?;
    let mut deserializer = serde_json::Deserializer::from_str(stdout.trim());
    let headers = RawHeaderEntries::deserialize(&mut deserializer)
        .and_then(|headers| {
            deserializer.end()?;

View on GitHub (pinned to 339751715c)

Solutions

Run the exact command manually from the configured cwd with a minimal env and inspect the exit status
Re-authenticate the underlying tool (e.g. gcloud auth login) and retry the MCP connection
Fix arguments/flags; verify required dependencies are installed at an absolute path
If the helper needs network, verify the environment allows it (proxy, DNS)

Example fix

# before: helper exits 1 because gcloud is logged out
# after: authenticate once, verify, then connect
gcloud auth application-default login
sh -c "$HTTP_HEADERS_HELPER" >/dev/null && echo ok   # must exit 0

Defensive patterns

Strategy: validation

Validate before calling

# Verify the helper exits 0 under helper-like conditions
cd "$MCP_CWD" && env -i PATH=/usr/bin:/bin HOME="$HOME" sh -c "$HTTP_HEADERS_HELPER" >/dev/null
[ "$?" -eq 0 ] || echo "helper exits non-zero; run it without >/dev/null to see why"

Type guard

fn is_helper_nonzero_exit(error: &anyhow::Error) -> bool {
    error.to_string().contains("exited with status")
}

Prevention

Re-authenticate credential CLIs on a schedule before they expire
Test the helper from the configured cwd with a minimal env
stderr is discarded — never rely on it for diagnostics
Alert on non-zero helper exits; they precede MCP connection failures

When it happens

Trigger: httpHeadersHelper exits non-zero: expired or invalid login in the underlying CLI, unauthenticated tool, DNS/network failure inside the helper, wrong arguments, or missing runtime dependencies.

Common situations: Cloud CLI helpers (gcloud, az, aws) with expired logins; pass/1Password lookups failing; corporate proxies blocking the helper's token request; wrong command arguments after a tool upgrade.

Related errors

AI-assisted analysis of openai/codex@339751715c (2026-08-25). Data as JSON: /api/errors/51af2f4eac435959. Report an issue: GitHub.