HAI-MCP
HAI-MCP is a model-agnostic MCP control-plane for bounding, observing, owner-gating, and recovering agent work—it governs work rather than executing it.
Check server health, ACTIVE lanes, focus, inbox count, and project status.
Open, inspect, recontract, close, or abandon versioned missions with concrete done criteria and evidence.
Authorize time-bounded session leases tied to a mission ID and contract version.
Deterministically classify planned/observed activity as on-contract or drift, including affected paths and blockers.
Enforce owner approval for sensitive actions via one-time nonces, ntfy/file delivery, Touch ID, or legacy ack.
Capture proof and close missions only against verified per-criterion evidence.
Manage focus/lanes with a maximum of two ACTIVE lanes.
Capture inbox items, distill intakes into one decision plus one next step, and park ideas/thoughts.
Propose/read/accept canonical NEXT_STEP.md files and read project artifacts.
Snapshot context with checkpoints and get minimal recovery advice.
Run over stdio or streamable HTTP with optional bearer-token binding.
It does not call LLMs, run shells, push git, delete files, provide a UI, or support concurrent missions.
Allows HAI-MCP to deliver owner-gated action approval codes as push notifications to the owner's phone via ntfy.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@HAI-MCP what's my current focus and next step?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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/
Related MCP server: codex-router
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:
Concern | What HAI-MCP exposes for it |
Mission contract |
|
Session leasing |
|
Activity classification |
|
Focus & lanes |
|
Owner gate | one-time nonces out-of-band ( |
Evidence & closure |
|
Inbox & intake |
|
Recovery |
|
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 anIntegerfield; 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_sessionbinds 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_activityclassifies 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 inHAI_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-assertedowner_ackflag — an honor system, surfaced as such byhai_health.
Mount table —
hai_bind_projectjoins a logicalproject_idto a device-local directory behindowner_ack + reason.Model-agnostic — same binary, same tools, same contract. Switch LLMs without rewriting governance.
Two transports — stdio (default) and
streamable-httpwith optional bearer-token binding (loopback only by default).Checkpoint & recover —
hai_checkpointsnapshots context;hai_recoverreturns 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, defaultStreamable-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-mcpHTTP binding to non-loopback hosts is refused unless
HAI_HTTP_TOKENis set. Seedocs/OWNER_GATE.mdand the--helpoutput.
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 = "<from open>",
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 = "<from lease>",
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 = "<from open>",
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 toHAI_OWNER_HOMEor an ntfy topic. Relaying it back asowner_code=<code>completes the action. The client never sees the code; only its hash is stored inHAI_HOME.touchid(macOS): setHAI_OWNER_CHANNEL=touchidon the server. The server shows a Touch ID prompt and returnsstatus: 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), andHAI_OWNER_TOUCHID_FALLBACK=fileonly 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~/.haiOwner channel:
$HAI_OWNER_HOME— default~/.hai-owner(deliberately outsideHAI_HOMEso the agent cannot read it)Per-project:
<project_path>/Projek-Managment/(legacy) or device mount + relative prefixes when aproject_idis boundMount 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 testsLimitations
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-intakepackages. The intake pipeline is a separate stack; coexistence is fine, fusion is not.Provide a UI. There is no dashboard. The control plane speaks MCP and writes JSON; visualisation is the client's job.
Multi-mission concurrency. Exactly one active mission globally. Open a new one only after the previous is closed (completed or abandoned).
Cross-device writes. Each device sees only its own mounts. The mount table is per-device; the contract is global.
Forward compatibility for major MCP bumps. The server pins
mcp>=1.9.0,<2; a v2 of MCP will require a separate migration slice.No revocation list / no kill-switch API. Lease invalidation happens via recontract, mission close, or
hai_stop; there is no out-of-band "revoke everything right now" tool.No automatic recovery from a corrupted
HAI_HOME. If the global state directory is corrupted, the server fails closed — by design, but recovery is manual (seehai_recover).
See docs/TOOL_CONTRACT.md for the full
gate matrix and docs/OWNER_GATE.md for the
owner-gate contract.
Tests
uv run pytest # full suite
uv run python scripts/stdio_smoke.py # stdio round-trip smokeThe repo carries 203 green tests as of the Touch ID owner-channel slice. CI status lives on the GitHub Actions page of the repository.
Contributing
The control plane is small on purpose — additions go through a contract slice:
Read
docs/TOOL_CONTRACT.md.Open an issue describing the tool / gate / state change.
Land it behind a
fail-closedslice with tests + plan indocs/plans/.
Pull requests that change gates, schemas, or the mount table without a matching plan will be asked to follow the same path.
License
MIT — see LICENSE. Copyright © 2026 Samuel Fleig.
Acknowledgements
HAI-MCP is one piece of Samuel Fleig's HAI stack. It stands on:
the Model Context Protocol specification,
the
mcpPython SDK (mcp>=1.9.0,<2),and the legacy
~/.config/hai-agent-mcpHermes bridge that this server replaces for control-plane work. Coexistence is supported; the bridge is not required.
Canonical HAI site: https://www.human-agent-interface.com/ · About Samuel Fleig: https://www.human-agent-interface.com/samuel/
Available Tools
23 toolshai_accept_next_stepA
Promote proposed (or provided) content to canonical NEXT_STEP.md. Requires owner_ack=true + reason.
Inputs: reason (required), owner_ack (required), project_path (required), content. Returns: result
hai_authorize_sessionC
Grant a time-bounded session lease tied to mission ID and exact contract version.
Inputs: role (required), mission_id (required), contribution (required), criterion_ids (required), +5 more. Returns: result
hai_check_activityC
Deterministically classify planned or observed activity against the mission contract.
Inputs: session_id (required), activity_step (required), evidence, criterion_id, +4 more. Returns: result
hai_checkpointC
Snapshot ACTIVE_CONTEXT and optional project artifacts under HAI_HOME/history/checkpoints.
Inputs: note, project_path. Returns: result
hai_close_missionC
Complete with verified per-criterion evidence, or abandon with owner_ack and reason.
Inputs: closure (required), mission_id (required), outcome_summary (required), contract_version (required), +2 more. Returns: result
hai_distillB
Reduce an intake to EXACTLY one decision + one next step; the server parks everything else.
Inputs: decision (required), intake_id (required), next_step (required), parklist. Returns: result
hai_drift_checkC
Lightweight mismatch check against the mission contract. Thin wrapper over hai_check_activity.
Inputs: session_id (required), activity_step (required), evidence, criterion_id, +4 more. Returns: result
hai_get_contractA
Return the exact canonical mission contract for a valid session lease (not a summary).
Inputs: session_id (required). Returns: result
hai_get_next_stepB
Read the canonical NEXT_STEP.md for a project (or report none).
Inputs: project_path (required). Returns: result
hai_healthA
Check HAI-MCP server health and optional project path usability. No model calls.
Inputs: project_path. Returns: result
hai_intakeA
Capture a raw thought immutably. Returns an intake id only — never actionable, never starts an agent.
Inputs: raw (required). Returns: result
hai_mission_startA
Fast start: declare problem + artifact + time limit. Thin wrapper over hai_open_mission (one canonical contract).
Inputs: owner (required), problem (required), artifact (required), done_criteria (required), +3 more. Returns: result
hai_open_missionC
Open a bounded mission with a versioned canonical contract. One active mission globally.
Inputs: owner (required), artifact (required), objective (required), done_criteria (required), +2 more. Returns: result
hai_parkB
Park a thought/meta item in HAI inbox without changing ACTIVE lanes.
Inputs: text (required), tags. Returns: result
hai_park_itemB
Park a mission-linked idea with full context. Grants no execution right; contract unchanged.
Inputs: idea (required), rationale (required), mission_id (required), trigger_event (required), +1 more. Returns: result
hai_proofA
Close a mission only against verified per-criterion evidence. Thin wrapper over hai_close_mission (completed).
Inputs: evidence (required), mission_id (required), outcome_summary (required), contract_version (required). Returns: result
hai_propose_next_stepA
Write NEXT_STEP.proposed.md (not canonical). Promote via hai_accept_next_step.
Inputs: content (required), project_path (required). Returns: result
hai_read_artifactsC
Read-only summary of HAI Projek-Managment run-contract artifacts.
Inputs: project_path (required), max_chars. Returns: result
hai_recontractB
Apply a visible field-level contract diff. Requires owner_ack=true; revokes all leases.
Inputs: reason (required), changes (required), mission_id (required), contract_version (required), +3 more. Returns: result
hai_recoverA
Return the smallest recovery next action from latest or named checkpoint (read-only advice).
Inputs: checkpoint_id. Returns: result
hai_set_focusB
Set focus and register an ACTIVE lane (max 2). Fails if a third ACTIVE is requested.
Inputs: focus_id (required), label, project_path. Returns: result
hai_statusB
Return ACTIVE lanes, focus, inbox count, and optional project next-step flags.
Inputs: project_path. Returns: result
hai_stopA
Hard day terminal: record the three answers, invalidate active leases; no next-day plan. Missions are not closed.
Inputs: day (required), clearer (required), loop_closed (required), agency_gained (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Several tools are explicitly thin wrappers of other tools (hai_mission_start over hai_open_mission, hai_drift_check over hai_check_activity, hai_proof over hai_close_mission), creating direct overlap. hai_park, hai_park_item, and hai_intake also blur the line between parking thoughts and capturing raw input. An agent selecting among these would frequently need to rely on subtle wording.
All tool names share the hai_ prefix and snake_case, which makes them readable. However, the pattern is inconsistent: some are noun-only (hai_health, hai_status, hai_proof), some are verb_noun (get_next_step, accept_next_step), and some are noun_verb (mission_start, drift_check).
23 tools is at the heavy end for a project-management server, especially given the explicit wrapper tools and separate parking/intake tools. It is not extreme enough to be chaotic, but the set feels over-factored.
The surface is heavily write-oriented: items can be parked, intakes captured, checkpoints snapshotted, and missions opened, but there are no read/list operations for intakes, parked items, checkpoints, or historical missions. This creates dead ends for agents trying to triage or inspect accumulated state.
Maintenance
Related MCP Connectors
Hosted MCP memory and agent control plane for durable conversations, jobs, and operations.
MCP-first control plane for ProAgentStore agents and private instances.
Human-agent interface for projects: you prioritize and decide, your AI agents execute. Over MCP.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Related MCP Servers
- AlicenseAqualityDmaintenanceManage voice AI agents from Claude Code, Cursor, VS Code, or any MCP-compatible assistant.33MIT
- AlicenseNot gradedqualityFmaintenanceA durable MCP control plane for starting, observing, steering, continuing, cancelling, and handing off long-running coding agents, with bounded MCP calls and persistent worktrees.23 npmMIT
- AlicenseNot gradedqualityBmaintenanceMCP server for agentic task orchestration and management, enabling AI agents to create goals, plan tasks with acceptance criteria, track dependencies, request human input, and provide proof of completion.27 npm3MIT
- AlicenseAqualityCmaintenanceEnables MCP clients to manage and orchestrate autonomous agents, budgets, and multi-agent workflows within the OpenMesha agentic operating system.91Apache 2.0