MCP command identity drift
Headroom CLI MCP server headroom package
When an MCP host cannot launch Headroom, fix the host config to point at an absolute executable path and the current MCP serve arguments. Avoid relying on a shell-only PATH entry.
Agent Quick Fix
[mcp_servers.headroom]
command = "/absolute/path/to/headroom"
args = ["mcp", "serve"]Resolve the executable path in the same environment the host will use, then write that absolute path into the MCP config.
command -v headroomSymptom
`headroom` works in an interactive shell, but Codex, Claude Desktop, or another MCP host reports that the server could not start or closes the MCP connection during launch.
Why This Happens
The moving contract is not just the Python package. It is the combination of package name, console script, MCP subcommand, and the PATH inherited by the host process.
Common Wrong Fixes
- Only running `pip install` again.
- Using `command = "headroom"` when the host does not inherit the tool directory.
- Assuming the package name and executable name always match.
Codex Search Keywords
Headroom CLI MCP server headroom package
Headroom CLI MCP server headroom mcp serve
"headroom" "mcp" "serve"
site:pypi.org/project headroom
https://github.com/chopratejas/headroom