humanchain-mcp 0.18.0

MCP server for HumanChain — AI agents pause for human expert guidance via the consult() tool.

humanchain-mcp

MCP server for HumanChain. Your AI agent pauses on a hard call and asks a real human expert, then continues with the answer. Exposes the async consult_start / consult_status pair (recommended) and a blocking consult fast-path.

Wires HumanChain into any MCP-aware agent (Claude Desktop, Claude Code, Cursor, Codex, Continue, …). When your agent hits a question that needs human judgment, it fires a consult; a vetted human answers; the agent continues with a grounded answer. If no human is available in time, an LLM fallback answers in their place (unless you set require_human=true) — and the result always tells you which of the two answered.

Full API reference: the /machine page on your configured HumanChain backend.

1. Install (pipx)

pipx install humanchain-mcp

pipx installs the server in its own isolated environment and puts a humanchain-mcp command on your PATH — that command is what your agent runs. Requires Python 3.10+.

• No pipx yet? python -m pip install --user pipx && python -m pipx ensurepath, then open a new terminal. On Windows: py -m pip install --user pipx then py -m pipx ensurepath, then reopen the terminal.
• Prefer plain pip? pip install humanchain-mcp also works — you'd then wire the server as python -m humanchain_mcp instead of the humanchain-mcp command shown below.

Verify the command is on your PATH:

humanchain-mcp --version

2. Get your key

Mint an API key on the /developer page of your HumanChain backend. You see it once. It is the only secret you need — and it goes in your agent's MCP config (next step), not on a command line and not in your code.

3. Wire it into your agent

Add HumanChain to your agent's MCP config. The shared/team key goes in the env block of this config — that is the one place it lives:

{
  "mcpServers": {
    "humanchain": {
      "command": "humanchain-mcp",
      "env": {
        "HUMANCHAIN_API_KEY": "hc_your_key_here"
      }
    }
  }
}

Restart the agent. Three tools appear: consult_start and consult_status (the pair you'll use) and consult (a blocking fast-path).

Where that config lives, by host:

Host	Where the mcpServers block goes
Claude Desktop	claude_desktop_config.json — Settings → Developer → Edit Config
Claude Code	.mcp.json in your project, or claude mcp add humanchain humanchain-mcp
Cursor	.cursor/mcp.json in your project (or global MCP settings)
Codex / other MCP hosts	the host's mcpServers block; command + env exactly as above

No MCP support in your host? Call the HTTP API directly (see /machine): POST /api/agent/consult/start, then poll GET /api/agent/consult/{id}/status, with header Authorization: Bearer hc_....

4. Your first consult — use the async pair

A human answer usually takes longer than an agent runtime's ~30-second tool-call limit, so the recommended pattern is start-then-poll:

1. consult_start(question="...") → returns a consult_job_id immediately.
2. consult_status(consult_job_id="...") → poll every ~10s until status is ANSWERED (or TIMED_OUT / FAILED).

The result leads with a plain banner so you can tell at a glance whether a human or the LLM answered, and what they said:

=== HUMAN ANSWER (provenance: human) ===
A HUMAN expert answered this consult.
answered by: ...  |  confidence: 0.8  |  latency: 41.0s

ANSWER:
<the human's answer>

--- structured result (machine-readable) ---
{ ...full JSON... }

…or, when no human was available in time:

=== LLM FALLBACK -- NOT a human (provenance: llm_fallback) ===
No human answered in time, so this answer was generated by an LLM, NOT a
human expert.
reason: no human available  |  confidence: 0.65
...

Common pitfall: don't re-start every turn (dropped thread)

Call consult_start once and keep the consult_job_id. Poll consult_status with that same id until it is terminal. Calling consult_start again on each turn opens a brand-new consult and loses the thread — the most common integration mistake in chat-style stacks.

Blocking consult (fast-path only)

consult(question="...") waits inline and returns the answer in a single call. Use it only for a sub-30-second smoke test. For any real consult — and always when require_human=true — use the async pair above, or the blocking call will trip your runtime's tool-call timeout and look broken.

Consult inputs

consult_start, consult_status, and consult share one input shape:

consult_start(
    question: str,                       # 10–4000 chars
    domain_tags: list[str] | None = None,
    target_responses: int = 1,           # 1 cheap/fast … 5 for consensus
    approval_method: Literal[
        "fastest", "consensus", "best_of_n", "all_must_agree"
    ] = "fastest",
    wait_seconds: int = 60,              # backend's wait budget for a human
    bypass_on_timeout: bool = True,      # fall back to LLM on timeout
    require_human: bool = False,         # never fall back to LLM
    context_brief: str | None = None,    # context shown to the human
    chain_id: str | None = None,         # scope routing to a private chain
) -> { "consult_job_id": ... }

See the API reference on your backend's /machine page for the full response shape and error types.

Environment variables

Variable	Default	Description
HUMANCHAIN_API_KEY	(required)	Your account API key.
HUMANCHAIN_BACKEND	https://humanchain-hub-demo.fly.dev	Hub backend URL. Override for self-hosted.
HUMANCHAIN_MODE	live	Set to sandbox to return synthetic responses without network calls.
HUMANCHAIN_TIMEOUT_MS	5000	HTTP timeout for Hub calls. (Distinct from consult.wait_seconds.)
HUMANCHAIN_LOG_LEVEL	INFO	Server log level.

Sandbox mode

Set HUMANCHAIN_MODE=sandbox and the server returns structurally-valid synthetic ConsultResponse objects without hitting the network. Use this in CI, agent unit tests, and during integration development — no credits burned, no humans woken. (Sandbox answers are synthetic, not a real human.)

Self-hosted backend

If you're running a self-hosted Hub, set HUMANCHAIN_BACKEND to your deployment URL. The MCP server speaks the same /api/agent/consult contract regardless of where the Hub is hosted.

Development

git clone https://github.com/M-C-Sigma/humanchain-the-hub
cd humanchain-the-hub/humanchain-mcp
pip install -e ".[dev]"
pytest

License

MIT.