# Headron

> Headron is an open-source MCP server for developer tools. Read-only verification and typed agent tools that map changed files to required checks. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, macOS, Linux, Windows
- **Repository:** https://github.com/hlintel/headron
- **MCP Registry name:** io.github.HLIntel/headron
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools)
- **Listing updated:** 2026-11-18

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
claude mcp add headron --env HEADRON_ROOT='<HEADRON_ROOT>' -- uvx headron-software
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "headron": {
      "command": "uvx",
      "args": [
        "headron-software"
      ],
      "env": {
        "HEADRON_ROOT": "<HEADRON_ROOT>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "headron": {
      "command": "uvx",
      "args": [
        "headron-software"
      ],
      "env": {
        "HEADRON_ROOT": "<HEADRON_ROOT>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "headron": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "headron-software"
      ],
      "env": {
        "HEADRON_ROOT": "<HEADRON_ROOT>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "headron": {
      "command": "uvx",
      "args": [
        "headron-software"
      ],
      "env": {
        "HEADRON_ROOT": "<HEADRON_ROOT>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "headron": {
      "command": "uvx",
      "args": [
        "headron-software"
      ],
      "env": {
        "HEADRON_ROOT": "<HEADRON_ROOT>"
      }
    }
  }
}
```

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

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Context7](https://ai-powered.com/mcp/context7): Context7 is a freemium MCP server for developer tools.
- [Chrome DevTools MCP](https://ai-powered.com/mcp/chrome-devtools-mcp-2): Chrome DevTools MCP is an open-source MCP server for browser automation.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [awesome-mcp-servers](https://ai-powered.com/mcp/awesome-mcp-servers-2): awesome-mcp-servers is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/headron
