Metadata-Version: 2.4
Name: humanchain-mcp
Version: 0.21.0
Summary: MCP server for HumanChain — AI agents pause for human expert guidance via the consult() tool.
Project-URL: Homepage, https://humanchain-hub-demo.fly.dev
Project-URL: Documentation, https://humanchain-hub-demo.fly.dev/machine
Project-URL: Repository, https://github.com/M-C-Sigma/humanchain-the-hub
Project-URL: Issues, https://github.com/M-C-Sigma/humanchain-the-hub/issues
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>=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

> 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)

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

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

```json
{
  "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:

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

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

## License

MIT.
