HAI-MCP

HAI-MCP · Model-agnostic MCP control-plane for the Human Agent Interface (HAI) approach

Why this repo exists

Agents are now driving shells, editors, browsers, and CI. Most of them work without a human in the loop long enough for the human to lose the thread. HAI — the Human Agent Interface — is an opinionated, evidence-based way to keep agentic work observable, bounded, owner-gated, and recoverable so a human can still *own* the work even when an agent is doing it.

HAI-MCP is the open-source, model-agnostic implementation of that approach. It is one of the pieces of Samuel Fleig's HAI stack — the part that any Model-Context-Protocol-speaking client can talk to, regardless of which LLM sits behind it.

Canonical site: https://www.human-agent-interface.com/ ·

About Samuel: https://www.human-agent-interface.com/samuel/

What "MCP control-plane" means here

MCP — the Model Context Protocol — is a standard JSON-RPC interface that lets a tool server expose tools, resources, and prompts to an LLM-backed client (Claude Code, Codex, Cursor, Grok, OpenCode, Hermes, …). The client discovers the server's tools and calls them during a conversation; the server stays stateless from the model's point of view.

A control-plane server is one that does not do the work itself — it governs how work is authorised, scoped, recorded, and handed back to the human. Concretely, an MCP control-plane:

HAI-MCP is deliberately not an agent runtime. It never calls an LLM, never runs shell, never pushes to git, and never deletes files. It is the judge — agents call it to ask *"may I?"* and to record *"I did"*.

Features

• One state engine, 23 tools — three surfaces (legacy control plane, mission lifecycle, daily-loop wrappers) sharing one hardened core.
• Strict fail-closed boundary — inputs are typed and rejected, not coerced. A String "2" is refused for an Integer field; the server stays reachable instead of silently mangling types.
• Versioned mission contracts — every mission has a contract with a monotonic version. Recontracting produces a visible field-level diff and revokes every existing lease.
• Time-bounded session leases — hai_authorize_session binds a lease to a mission id, a contract version, a duration, a role, a contribution, and a claimed criterion set.
• Deterministic drift check — hai_check_activity classifies planned or observed activity against the contract without ever calling an LLM.
• Two-principal owner gate:
• Default (nonce): the server delivers a one-time code to the owner channel (HAI_OWNER_HOME / file, or ntfy). The client never sees the code. The code is bound to the exact change, single-use, expiring; only the hash is stored in HAI_HOME.
• `touchid` (macOS): the server process shows a Touch ID prompt for that exact change. There is no code. The agent's follow-up call applies it; the client cannot approve itself.
• `ack_legacy`: the old self-asserted owner_ack flag — an honor system, surfaced as such by hai_health.
• Mount table — hai_bind_project joins a logical project_id to a device-local directory behind owner_ack + reason.
• Model-agnostic — same binary, same tools, same contract. Switch LLMs without rewriting governance.
• Two transports — stdio (default) and streamable-http with optional bearer-token binding (loopback only by default).
• Checkpoint & recover — hai_checkpoint snapshots context; hai_recover returns the smallest recovery next action.
• 203 tests green — the engine is covered; the slice remains open for the learning-budget and owner-instrument follow-ups.

Install & run

Requires Python ≥ 3.12 and uv.

git clone https://github.com/smlfg/hai-mcp.git

cd hai-mcp uv sync --all-extras uv run hai-mcp # stdio transport, default

Streamable-HTTP transport:

HAI_TRANSPORT=streamable-http \

HAI_HTTP_HOST=127.0.0.1 \ HAI_HTTP_PORT=8765 \ HAI_HTTP_TOKEN="$(openssl rand -hex 32)" \ uv run hai-mcp

HTTP binding to non-loopback hosts is refused unless HAI_HTTP_TOKEN is

set. See docs/OWNER_GATE.md and the --help output.

Sample usage — wiring the server into a client

The server is transport-agnostic; every MCP client gets the same 23 tools. Drop the snippet into the client's MCP config and restart.

Claude Code / Claude Desktop

{

"mcpServers": { "hai": { "command": "uv", "args": [ "run", "--directory", "/absolute/path/to/hai-mcp", "hai-mcp" ], "env": { "HAI_HOME": "/home/you/.hai", "HAI_OWNER_HOME": "/home/you/.hai-owner" } } } }

Cursor

Cursor plugin: this repo is also a Cursor plugin (.cursor-plugin/plugin.json + mcp.json). It starts the server from PyPI with uvx hai-mcp, state goes to ~/.hai and ~/.hai-owner by default. Requires uv.

Manual config:

{

"mcpServers": { "hai": { "command": "uv", "args": [ "run", "--directory", "/absolute/path/to/hai-mcp", "hai-mcp" ], "env": { "HAI_HOME": "/home/you/.hai", "HAI_OWNER_HOME": "/home/you/.hai-owner" } } } }

Codex / Hermes / any MCP stdio client

Same shape — point at the uv run --directory … hai-mcp command and pass the two env vars. More snippets live in docs/client-snippets/.

Sample usage — driving the protocol

A typical agent loop calls HAI-MCP before it acts and after it acts.

1. Open a bounded mission

hai_mission_start(

problem = "Refactor the evaluator harness to be deterministic.", artifact = "Pull request titled 'evaluator: deterministic harness'.", done_criteria = [ {"id": "C1", "description": "Two A/B cases produce identical verdicts on three reruns."}, {"id": "C2", "description": "Harness runs offline; no live network calls."}, ], owner = "samuel", time_limit_hours = 6, non_goals = ["Do not touch the MCP server.", "Do not change contract shapes."], constraints = {"python": ">=3.12", "branch": "slice/eval-determinism"}, )

2. Authorise a session lease

hai_authorize_session(

mission_id = " ", contract_version = 1, agent_identity = "codex-cli", role = "implementer", contribution = "Deterministic A/B harness", expected_result = "Green pytest with frozen inputs.", duration_minutes = 90, criterion_ids = ["C1", "C2"], device_id = "mbp-mirgraatin", harness_id = "codex-cli/0.45", )

3. Check an activity before running it

hai_check_activity(

session_id = " ", activity_step = "Replace random.seed with a seeded fixture in tests/test_eval_ab.py", criterion_id = "C1", affected_paths = ["tests/test_eval_ab.py", "tests/fixtures/ab/case1.json"], )

→ {"verdict": "on_contract", ...}

4. Close with evidence

hai_proof(

mission_id = " ", contract_version = 1, outcome_summary = "A/B cases produce identical verdicts on three reruns; harness offline.", evidence = { "C1": {"command": "pytest tests/test_eval_ab.py -q", "exit_code": 0, "reruns": [0, 0, 0]}, "C2": {"command": "pytest tests/test_eval_ab.py -q --offline", "exit_code": 0}, }, )

5. Owner-gated promotion

For hai_accept_next_step, hai_recontract, or abandoning a mission, the first call without owner_code asks the owner out of band.

• `file` / `ntfy`: a one-time code is delivered to HAI_OWNER_HOME or an ntfy topic. Relaying it back as owner_code= completes the action. The client never sees the code; only its hash is stored in HAI_HOME.
• `touchid` (macOS): set HAI_OWNER_CHANNEL=touchid on the server. The server shows a Touch ID prompt and returns status: owner_approved. Call the same tool again with the same arguments (no code) to apply that exact change. Optional: HAI_OWNER_TOUCHID_TIMEOUT (default 60), HAI_OWNER_TOUCHID_HELPER (a compiled binary), and HAI_OWNER_TOUCHID_FALLBACK=file only when Touch ID cannot run.

The approval is bound to the exact change and is single-use. On a Mac, uv run python scripts/manual_touchid.py prompt and … gate exercise the real sensor; CI mocks the helper. Detail: docs/OWNER_GATE.md.

State layout

• Global: $HAI_HOME — default ~/.hai
• Owner channel: $HAI_OWNER_HOME — default ~/.hai-owner (deliberately outside HAI_HOME so the agent cannot read it)
• Per-project: /Projek-Managment/ (legacy) or device mount + relative prefixes when a project_id is bound
• Mount table: HAI_HOME/core/projects.json

All writes are resolved and confined to these roots.

Project layout

hai-mcp/

├── docs/ │ ├── TOOL_CONTRACT.md # normative tool contract (gates, errors, schemas) │ ├── OWNER_GATE.md # nonce + ack_legacy owner-gate spec │ ├── BUILD_HANDOFF.md │ ├── client-snippets/ # ready-to-paste mcp.json snippets │ ├── eval/ # A/B harness contract │ ├── plans/ # dated design slices │ └── visuals/ # mission-lifecycle banner assets ├── scripts/ # stdio smoke + impact-eval runner ├── src/hai_mcp/ # the server └── tests/ # 203 tests

Limitations

HAI-MCP is intentionally narrow. It does not:

• Call any LLM. The server is dumb on purpose — governance is a separate concern from generation.
• Execute code, run shells, push git, or delete files. It refuses tools like *"commit & push"*, *"run pytest"*, *"rm -rf"*. Agents are expected to do those things and report back via hai_check_activity / hai_proof.
• Merge with `hai-intake` packages. The intake pipeline is a separate stack; coexistence is fine, fusion is not.
• Provide a UI. There is no das