Metadata-Version: 2.4
Name: humanchain-mcp
Version: 0.15.0
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://humanchain.ai/docs
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-email: HumanChain <hello@humanchain.ai>
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](https://humanchain.ai) — AI agents pause for
> human expert guidance via a single `consult` tool.

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: **https://humanchain.ai/docs**

## Install

```bash
pip install humanchain-mcp
```

Requires Python 3.10+.

## Configure your agent

Sign up at https://humanchain.ai/signup and grab an API key, then add
the server to your agent's MCP config:

```json
{
  "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 a single tool named `consult`. Its signature
matches the documented Python SDK:

```python
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](https://humanchain.ai/docs/api/consult/) 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

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