Headron
Read-only verification and typed agent tools that map changed files to required checks
- Pricing
- Open source
- Platforms
- CLI, macOS, Linux
- Runs
- Locally
- Version
- 3.62.0
- Listing updated
- today
Similar MCP servers
About Headron
Headron is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.
Headron treats a skipped check as a failure to report, not a pass. Its atlas.yaml file declares which checks a file owes, and the CLI reports PASS, FAIL, SKIP or NOT RUN for each, so an agent cannot quietly claim success when a test never ran. The README is explicit that it is not a coding agent, model or test framework and does not prove code is correct.
The MCP interface is read-only. It is distributed as the headron-software PyPI package over stdio and needs HEADRON_ROOT pointing at a checkout containing the atlas. Running headron init writes AGENTS.md, CLAUDE.md, MCP configs for Codex and Cursor and a pre-commit hook, and --no-wiring skips that.
A separate hosted Mind API plans declared changes; it is paid and needs a key, while the command line works without it. The README records results such as 31 of 31 planted breaks refused across 20 toolchains and says its figures have stated limits. Licence is MIT.
Install
Run in a terminal
claude mcp add headron --env HEADRON_ROOT='<HEADRON_ROOT>' -- uvx headron-softwareAdd to claude_desktop_config.json
{
"mcpServers": {
"headron": {
"command": "uvx",
"args": [
"headron-software"
],
"env": {
"HEADRON_ROOT": "<HEADRON_ROOT>"
}
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"headron": {
"command": "uvx",
"args": [
"headron-software"
],
"env": {
"HEADRON_ROOT": "<HEADRON_ROOT>"
}
}
}
}Add to .vscode/mcp.json
{
"servers": {
"headron": {
"type": "stdio",
"command": "uvx",
"args": [
"headron-software"
],
"env": {
"HEADRON_ROOT": "<HEADRON_ROOT>"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"headron": {
"command": "uvx",
"args": [
"headron-software"
],
"env": {
"HEADRON_ROOT": "<HEADRON_ROOT>"
}
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"headron": {
"command": "uvx",
"args": [
"headron-software"
],
"env": {
"HEADRON_ROOT": "<HEADRON_ROOT>"
}
}
}
}Using several servers? Build one config file with the MCP config generator.
Configuration
HEADRON_ROOTPath to a checkout of the Headron atlas (atlas.yaml) the tool reads.Required
What it does
- Check routing
- headron port tells an agent what a file owes before it is edited.
- Honest verdicts
- Checks that cannot run report SKIP or NOT RUN, never a pass.
- Done gates
- headron verify runs the declared gates after a change.
- Optional commit hook
- A pre-commit hook can run checks for developer or agent changes.
- Receipts
- Verdicts carry receipts that can be checked with headron verify --receipt.
- Mind API planning
- A hosted, paid API plans declared changes.
Good for
- Stop an agent from committing when required tests never ran
- Tell an agent which checks apply to a file before editing
- Wire AGENTS.md and MCP configs into a repository
- Audit past verification outcomes
Pricing
Open source
MIT licensed; hosted Mind API is paid.
Headron FAQ
What does the MCP server need?
The HEADRON_ROOT environment variable pointing at a checkout containing atlas.yaml.
Is the Mind API free?
No. It is hosted, paid and needs a key; the command line works without it.
Does it prove my code is correct?
No. The README says it is not proof of correctness.
How do I install it?
Run uv tool install headron-software, then headron doctor.
Is Headron free?
Yes. Headron is open source, so you can use and self-host it for free.
How do I add Headron to Claude Code?
Run this command in your terminal: claude mcp add headron --env HEADRON_ROOT='<HEADRON_ROOT>' -- uvx headron-software
What are the best alternatives to Headron?
The closest alternatives to Headron are REA, Context7, Chrome DevTools MCP, Codebase Memory and GitHub.
Where this comes from
- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.


