Skip to content
MCP server

Headron

Read-only verification and typed agent tools that map changed files to required checks

Runs locallyStatus and history
Install
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-software

Add 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.

How AIPoweredBot checks servers