humanchain-mcp 0.17.1

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

humanchain-mcp

MCP server for HumanChain. AI agents pause for human expert guidance via the consult tool (and the async consult_start / consult_status pair).

Wires HumanChain into any MCP-aware coding agent (Claude Desktop, Cursor, Continue, Claude Code, Cody, …). When your agent hits a question that needs human judgment, it calls consult(); a vetted human answers; the agent continues with a grounded response. If no human is online, a single-voice LLM fallback (Groq Llama 3.3 70B) answers in their place.

Full documentation: the /machine and /llms.txt pages on your configured HumanChain backend.

Install

pip install humanchain-mcp

Requires Python 3.10+.

Configure your agent

Mint an API key on the /developer page of your HumanChain backend, then add the server to your agent's MCP config:

{
  "mcpServers": {
    "humanchain": {
      "command": "python",
      "args": ["-m", "humanchain_mcp"],
      "env": {
        "HUMANCHAIN_API_KEY": "hc_your_key_here"
      }
    }
  }
}

Restart your agent. The consult tool is now available.

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.

The consult tool

The MCP server registers consult (blocking) plus the async pair consult_start / consult_status. The consult signature matches the documented Python SDK (use the async pair for any consult that waits on a human, including every require_human=true call):

consult(
    question: str,
    domain_tags: list[str] | None = None,
    target_responses: int = 1,
    approval_method: Literal[
        "fastest", "consensus", "best_of_n", "all_must_agree"
    ] = "fastest",
    wait_seconds: int = 60,
    bypass_on_timeout: bool = True,
    require_human: bool = False,
    context_brief: str | None = None,
) -> ConsultResponse

See the API reference on your backend's /machine page for the full parameter and response shape, error types, and the @hc/... shorthand mapping.

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.

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.