humanchain-mcp

HumanChain lets your AI agent ask a real person. When the agent hits a call that needs judgment, it fires a consult: the question — with the answer choices the agent wrote for it — lands on the phone of someone on your panel; they tap; the answer comes back to the agent marked as a human's, with who answered, how confident they were, and how long it took. If no human answers in time, the agent is told so plainly; it is never handed a machine's guess dressed as a person's.

This package is the plug: an MCP server that exposes consult, consult_start and consult_status to Claude Code, Claude Desktop, Codex, Cursor and any other MCP-aware agent. It is MIT-licensed — copy it, embed it, ship it in your own stack. Everything that happens after the question leaves your machine — who is asked, how, and what the answer is worth — happens at HumanChain behind your key.

Setup — one command

You need an invite. Sign in at app.humanchain.ai/master with your invite code; the key screen shows a command with your key already in it. Copy it, paste it into a terminal, press Enter:

curl -fsSL https://app.humanchain.ai/install | HC_KEY=hc_your_key_here sh

It finds or installs Python and pipx, removes any older copy that would shadow the new one, installs this server, registers it in Claude Code, Codex and Claude Desktop (whichever you have, with full paths so they find it), runs a health check, and prints ✓ DONE with the next step. Safe to run again. Nothing to edit by hand.

Then, in your agent:

ask my HumanChain panel: "…your question…" and wait for a human

Prefer to do it by hand? pipx install humanchain-mcp, then give your agent the command humanchain-mcp with two environment values: HUMANCHAIN_API_KEY and HUMANCHAIN_BACKEND=https://app.humanchain.ai (there is no default backend, on purpose — your questions go only where you say). Optional: HUMANCHAIN_CHAIN_ID pins every consult to one chain.

What the agent sees

Three tools. consult_start fires a consult and returns a job id; consult_status polls it; consult is the blocking form and turns itself into a job when the wait is longer than a tool call can hold, so a question is never sent twice.

Every consult carries its own answer choices. answer_format is required — binary with the two labels the agent writes for the question, mcq/msq with named options, rating_scale, or free_text on purpose. The desk never invents Approve / Reject on the agent's behalf; the person on the phone sees the choice the question actually needs.

Every reply starts with a SCOPE: line naming the chain the question went to, and every answer states its provenance: human, or llm_fallback when nobody answered in time (which happens only if you allowed it).

=== HUMAN ANSWER (provenance: human) ===
answered by: anonymous  |  confidence: 0.7  |  latency: 21.0s
ANSWER: City loft — central and walkable, €4,500

Check it works

HUMANCHAIN_API_KEY=hc_your_key_here HUMANCHAIN_BACKEND=https://app.humanchain.ai humanchain-mcp doctor

Three [PASS] lines: config, backend reachable, key accepted with your balance.

Clean slate

curl -fsSL https://app.humanchain.ai/install | sh -s -- --uninstall

Pricing

Your invite comes with a free allowance of consults. After that, top up credits in the console; each consult costs credits, and more consult types are available on your plan. Details at humanchain.ai/pricing.

Documentation

Everything you need is on this page. Start at app.humanchain.ai/developer (invite code required); the key screen there shows your install command with the key filled in.

Environment variables

License

MIT. The plug is free; the desk is HumanChain's.