# HumanChain: llms.txt > MCP-native helpline for AI agents. When an agent hits a question > that requires human judgment, it pauses, asks a vetted expert via > the consult() tool, and continues with a real answer. ## Identity - Product: HumanChain (a Sanctity AI product) - Surface: MCP server (PyPI: humanchain-mcp). The public API is not yet live. - Domain: https://humanchain.ai - API host: not yet public. humanchain-mcp requires you to configure your own backend host (HUMANCHAIN_BACKEND); the package ships no default by design. - License (client packages): MIT - Contact: see humanchain.ai - Security: see humanchain.ai ## Summary in one paragraph HumanChain lets AI agents call human experts mid-task. Developers install the MCP server (pipx install humanchain-mcp), configure an API key, and the agent gains three tools: consult, consult_start, and consult_status. The agent passes a question and a chain id; HumanChain routes the question to a qualified expert from that chain via Microsoft Teams or a web inbox; the expert answers in plain language; the agent reads back a TRANSCRIPT (the question and the answers given, each labeled by source) and continues. HumanChain is the mailman, not the author: it never writes answers as itself. When humans can't answer in time, the agent can either fail or fall back to an LLM, depending on the require_human flag. ## Audiences - Master clients: companies running AI agent products. They invite their own experts into chains and expose those experts to their agent via HumanChain. - Contributors: experts who answer consults. They join a chain by master invitation, calibrate in their domain, and answer routed questions. - Agents: any AI agent that can call an MCP tool or HTTP endpoint. Tested hosts include Claude Desktop, Claude Code, Cowork, Cursor, Continue, and custom agents using the Python SDK. ## Install (60 seconds) ``` pipx install humanchain-mcp ``` (If you don't use pipx, `pip install humanchain-mcp` also works.) MCP host configuration (Claude Desktop / Cowork): ```json { "mcpServers": { "humanchain": { "command": "humanchain-mcp", "env": { "HUMANCHAIN_API_KEY": "hc_live_...", "HUMANCHAIN_BACKEND": "https://humanchain.ai", "HUMANCHAIN_CHAIN_ID": "00000000-0000-4000-8000-00000000fa01", "HUMANCHAIN_TIMEOUT_MS": "660000" } } } } ``` For the trial, set `HUMANCHAIN_CHAIN_ID` to the team chain `00000000-0000-4000-8000-00000000fa01` (required). Every consult then routes to your team automatically: you never pass chain_id per call, and you never create a chain (chain creation is an admin operation, not the tester path). ## MCP tools exposed Recommended pattern is async: most real consults take longer than a host's tool-call timeout, so fire consult_start, then poll consult_status. - consult_start: fire-and-return; returns consult_job_id immediately. The recommended entry point for real consults. - consult_status: poll a started consult job until it reaches a terminal status. - consult: synchronous consult; blocks until answered or timeout. Use only for low-latency cases that fit inside a generous host timeout. Input shape (all tools): - question (string; required UNLESS `card` is given): the question for the human - card (object, optional): a TYPED question card for a STRUCTURED answer (mcq/msq/binary/rating/ranking/scalar) instead of free text. Provide EITHER question OR card; the card's prompt.text is the question. Shape {question_type, context?, prompt, answer}; question_type in open_ended|dichotomous|mcq|msq|ranking|scalar with a matching answer.input (text|binary|single_select|multi_select|rank|scale); options/choices/items are {id,label}. The response then carries a typed `aggregate`. - context_brief (string, optional, max 2000): background shown to the human as its own block on the card - answer_format (free_text | mcq | msq | rating_scale | binary, default free_text): flat single-question structured-answer shape (the card is the richer form) - options (array of strings): the choices for answer_format mcq/msq - reuse_within_seconds (integer, optional): opt-in answer reuse ("memory") - a repeat of the EXACT same question + context_brief that already got a HUMAN answer within the window returns it immediately (cached=true, 0 credits) - chain_id (string; for the trial REQUIRED = 00000000-0000-4000-8000-00000000fa01, set once via HUMANCHAIN_CHAIN_ID): which expert panel to route to - target_responses (integer, 1-5, default 1) - wait_seconds (integer, 10-1800, default 60; clamped by plan: free 120s, paid 1800s) - require_human (boolean, default false) - domain_tags (array of strings, optional) - approval_method (fastest | consensus | best_of_n | all_must_agree, default fastest) ## Response shape (from consult / consult_status) ```json { "consult_job_id": "", "status": "QUEUED|IN_FLIGHT|CLARIFY_PENDING|ANSWERED|TIMED_OUT|FAILED|CANCELLED", "response": { "provenance": "human|llm_fallback|mixed|escalated", "response_text": "...", "responder_id": "", "responder_handle": "", "confidence": 0.0..1.0, "latency_ms": , "cost_credits": , "cached": , "fallback_reason": "", "domain_tags_matched": ["..."], "raw_responses": [ { "responder_id": "", "responder_handle": "", "response_text": "...", "confidence": 0.0..1.0, "submitted_at_ms": , "source": "human|llm_fallback|client_llm" } ], "original_question": "", "reframed_question": "", "disclaimers": ["plain-English honesty notes"], "confidence_detail": { "label": "Low|Moderate|High", "score": 0.0..1.0, "agreement": "how much the answerers agreed", "is_calibrated": , "note": "disclaimer" }, "aggregate": { "_comment": "present ONLY for a typed `card`; null for a free-text consult", "question_type": "open_ended|dichotomous|mcq|msq|ranking|scalar", "headline": "the typed point answer (also copied into response_text)", "distribution": { "...": "per-type tally (counts / per-option % / mean-ranks / histogram)" }, "agreement": "0.0..1.0, measured the right way for the type", "divergence": "the minority / outliers, in words - never hidden", "confidence": { "label": "Low|Moderate|High", "score": 0.0..1.0, "note": "disclaimer" } } }, "error": "" } ``` ## The honest transcript (read these fields) HumanChain returns a transcript, not an authored answer: - Each row in `raw_responses` carries a `source`: `human`, `llm_fallback` (HumanChain's default LLM), or `client_llm` (the master's own configured model). Never treat a non-human row as a human judgment. - `disclaimers` are plain-English honesty notes (this represents what humans answered; HumanChain does not author or verify it; accountability rests with the responders). - `confidence_detail` reads how much the answerers AGREED, not whether they were right. Its `is_calibrated` flips true once the answerers build enough outcome-marked history. - On paid tiers, `reframed_question` is the clarified question the human actually saw (meaning preserved; no opinion injected). On free, it is null. - `responder_handle` may be a real name, a team label (e.g. "Legal team"), or an anonymous token, depending on the chain's visibility mode. The default is anonymous ("darkroom"). ## When an agent should consult Recommend calling consult() when: 1. Model confidence is below a configured threshold. 2. The action is irreversible or high-impact. 3. The question is jurisdiction-, time-, or context-sensitive in a way the model can't verify from its own knowledge. 4. The master client has marked the workflow as human-required. Strong fit domains: legal (contract clauses, regulatory interpretation), healthcare (triage, clinical decision support), finance/compliance (KYC thresholds, regulated workflows), engineering/DevOps (deploy plans, rollback paths), product/strategy (ambiguous prioritization), high-value customer support. ## Fallback (the canonical rule) A human answer within wait_seconds is ALWAYS returned (provenance="human"). The two flags only govern the no-human-in-time case, and require_human always wins: - require_human=true: raises humanchain_no_human_available (never an LLM; overrides bypass_on_timeout). No credit charged. - require_human=false + bypass_on_timeout=true (default): LLM fallback, labeled provenance="llm_fallback" / source="llm_fallback" (groq-llama-3.3-70b-versatile by default; if the master configured bring-your-own-LLM it is used instead and labeled source="client_llm", with graceful fall-through to the default on error, so a consult always returns something honestly labeled). - require_human=false + bypass_on_timeout=false: raises humanchain_timeout (no LLM). ## Security Stated conservatively, and each line is bound to the code that proves it (see the claims register; if we cannot prove it, it is not here). - API keys are stored as SHA-256 hashes. The plaintext key is shown once, at issuance. - Account passwords are hashed with bcrypt. - Per-master integration credentials are encrypted at rest with Fernet (AES-128-CBC + HMAC-SHA256). - Every admin action is written to an append-only audit log. - Hub API traffic is HTTPS-only. - Hosted on Fly.io; disk-level encryption of database volumes is provided by the platform, not by HumanChain. We do not hold SOC 2 certification and we do not offer a HIPAA BAA. If a page ever says otherwise, this line is the correct one. ## Links - Marketing: https://humanchain.ai - Docs: https://humanchain.ai/docs - This file: https://humanchain.ai/llms.txt - PyPI package: humanchain-mcp - Email: the preview team Document version 1.4 (apex) ยท claims reconciled to code 2026-07-17; every claim bound in 20-backend/CLAIMS-REGISTER.md.