Metadata-Version: 2.5
Name: humanchain-mcp
Version: 0.27.2
Summary: MCP server for HumanChain — AI agents pause for human expert guidance via the consult() tool.
Project-URL: Homepage, https://humanchain.ai
Project-URL: Documentation, https://app.humanchain.ai/developer
Author: HumanChain
License: MIT
Keywords: ai-agents,expert-routing,human-in-the-loop,humanchain,mcp,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp<2,>=1.0.0
Requires-Dist: pydantic>=2.6.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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](https://humanchain.ai) behind your key.

## Setup — one command

You need an invite. Sign in at **[app.humanchain.ai/master](https://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:

```bash
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

```bash
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

```bash
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](https://humanchain.ai/pricing).

## Documentation

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

## Environment variables

| Variable | Required | Meaning |
| --- | --- | --- |
| `HUMANCHAIN_API_KEY` | yes | your key (`hc_…`), from the key screen |
| `HUMANCHAIN_BACKEND` | yes | `https://app.humanchain.ai` — no default, by design |
| `HUMANCHAIN_CHAIN_ID` | no | pin every consult to one chain (the chain page's command sets it) |
| `HUMANCHAIN_MODE` | no | `sandbox` returns synthetic answers with no key, for CI |
| `HUMANCHAIN_TIMEOUT_MS` | no | HTTP timeout for hub calls (not the human wait) |

## License

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