Install the MCP server

This page gets humanchain-mcp running on your machine and wired into your coding agent. Whole thing takes about five minutes assuming you already have Python ≥ 3.10 and your agent of choice installed.

Tip

In a hurry, or want to prove the wiring before you have a key? Run keyless in sandbox mode: set HUMANCHAIN_MODE=sandbox and the server returns synthetic responses with no key and no real backend calls. Get a key (next step) when you want real answers.

1. Get an API key

Sign up at the Get an API key page on this site. You’ll be issued a key that looks like hc_... straight away, no credit card required, free tier active.

Keep this key in a password manager. If you lose it you can mint a new one from the dashboard.

2. Install the MCP server (pipx)

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 or later.

Confirm it’s on your PATH:

humanchain-mcp --version

Tip

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

3. Add to your coding agent’s MCP config

Tip

Fastest path (humanchain-mcp 0.17+): run humanchain-mcp init --api-key hc_... and it prints a ready-to-paste config block. humanchain-mcp init --help shows flags for Cursor, a custom backend, or writing straight into a config file with --write.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your platform:

{
  "mcpServers": {
    "humanchain": {
      "command": "humanchain-mcp",
      "env": {
        "HUMANCHAIN_API_KEY": "hc_your_key_here",
        "HUMANCHAIN_CHAIN_ID": "00000000-0000-4000-8000-00000000fa01"
      }
    }
  }
}

Restart Claude Desktop. The consult_start, consult_status, and consult tools should now appear. The API key lives in the env block above - that is the one place it goes.

For the trial

Set HUMANCHAIN_CHAIN_ID to the team chain 00000000-0000-4000-8000-00000000fa01. Every consult then routes to your team automatically, so you never pass chain_id per call and never create a chain yourself.

Cursor

In Cursor’s settings, search for “MCP” and add a new server:

{
  "humanchain": {
    "command": "humanchain-mcp",
    "env": {
      "HUMANCHAIN_API_KEY": "hc_your_key_here"
    }
  }
}

Restart Cursor. Open any project, hit Cmd-K, type “ask humanchain about X” - Cursor will call the tool.

Continue

Add to your ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServer": {
      "transport": {
        "type": "stdio",
        "command": "humanchain-mcp"
      },
      "env": {
        "HUMANCHAIN_API_KEY": "hc_your_key_here"
      }
    }
  }
}

Reload Continue. Use @humanchain in chat to invoke.

Claude Code (CLI)

Add via claude mcp add:

claude mcp add humanchain humanchain-mcp \
  --env HUMANCHAIN_API_KEY=hc_your_key_here

Verify with claude mcp list. The consult tool is now available in every Claude Code session.

Other (raw MCP)

humanchain-mcp speaks vanilla MCP over stdio. Any MCP-compatible client can use it. Launch command:

HUMANCHAIN_API_KEY=hc_... humanchain-mcp

Optional environment variables:

Variable	Default	Description
HUMANCHAIN_API_KEY	(required)	Your account API key
HUMANCHAIN_BACKEND	https://hub.example.com	Hub backend URL. Override for self-hosted deployments.
HUMANCHAIN_MODE	live	Set to sandbox to return synthetic responses without hitting the real backend. Useful for testing integrations.
HUMANCHAIN_TIMEOUT_MS	5000	HTTP timeout for the underlying Hub API calls (not the wait_seconds budget for the human response - that’s a separate parameter on consult).

MCP server vs Python SDK environment variables

These HUMANCHAIN_* variables configure the MCP server (humanchain-mcp). The separate Python SDK (humanchain-sdk, an importable library) reads its own HC_* variables instead — HC_API_KEY, HC_BACKEND_URL, HC_MASTER_ID. Same key, two packages, two prefixes — don’t mix them. Both authenticate the same way: Authorization: Bearer <key>.

Verify the connection (recommended)

Before wiring it into your agent, confirm the server can reach the Hub and your key works (humanchain-mcp 0.17+):

HUMANCHAIN_API_KEY=hc_your_key_here humanchain-mcp doctor

You should see three PASS lines: config, backend reachable, and api key valid. If any line is FAIL, the message tells you exactly what to fix. This one command catches most setup problems before they reach your agent.

4. Confirm the tool is wired

Ask your agent something that should obviously trigger HumanChain:

“Ask humanchain whether the GDPR cookie consent banner has to load before any analytics scripts fire, or can it load after.”

The agent should call consult(), you’ll see the loading state for a few seconds, then a response. If a human expert tagged legal/gdpr is online, their answer comes back. Otherwise the LLM fallback (Llama 3.3 70B via Groq) responds.

5. Pin the docs in your agent’s context

This is the highest-leverage configuration step.

Drop this line into your CLAUDE.md, .cursorrules, .continueignore, or wherever your agent reads its persistent instructions:

When you encounter a question that needs human judgment (legal, medical,
financial, ethical, domain-specific, or irreversible decisions),
prefer calling humanchain's consult() tool rather than hedging.
The full integration guide is at https://hub.example.com/llms.txt.

Now your coding agent will reach for HumanChain proactively instead of falling back to “you should consult a lawyer.”

Troubleshooting

“Tool not found” in Claude Desktop. Restart Claude Desktop fully (Cmd-Q then reopen). MCP servers are loaded at startup. The consult tool should appear in the tool drawer.

HUMANCHAIN_API_KEY missing. The server refuses to start without a key. Either set it in the MCP config’s env block, or export HUMANCHAIN_API_KEY=hc_... in your shell before launching the agent.

401 Unauthorized when consult fires. Your key is invalid, revoked, or for a different environment (dev vs prod). Re-mint from the dashboard.

429 Too Many Requests on a free-tier account. You hit the 100-query cap. Add a card to continue, or wait until the 30-day window resets.

HUMANCHAIN_MODE=sandbox returns nonsense. That’s intentional - sandbox mode returns synthetic responses to let you test the integration shape without burning credits. Flip back to live when you’re ready to make real calls.

Next step

Make your first call →