Documentation | HUMΛN Docs

Overview

The HUMΛN Companion is not a separate chatbot bolted onto MCP — it is the Tier 1 entry point. The human.ask tool relays your message through the same intent-aware pipeline as the web Companion: classify the turn, search delegated KB, shape a brief, and return an answer or an intent_action proposal for human approval.

Hosted MCP maps human.ask → POST /v1/companion/chat in apps/api/src/routes/companion/index.ts. The Worker streams tokens when the upstream response is text/event-stream (canStreamTool('human.ask') in apps/mcp-worker/src/dispatcher.ts).

Why Companion-as-tool?

Magic by default — one tool call instead of wiring intent, KB, and routing yourself

Same governance — delegation scopes (companion:chat, KB read scopes) gate what Companion can see

Fourth Law — low-confidence turns surface clarifying questions or escalation, not silent guesses

Session continuity — pass session_id so follow-up turns retain intent context across tool calls

Think of it like: Embedding the Companion widget, but for an AI agent that already speaks MCP.

Shipped surfaces

Surface	Path / tool
MCP tool name	`human.ask`
API route	`POST /v1/companion/chat`
KB search (Tier 1 sibling)	`human.companion.kb_search` → `GET /v1/companion/kb/search`
Streaming	SSE pipe on hosted `/sse` + `/messages` when `Accept: text/event-stream`
Local bridge	`npx @human/mcp` forwards `tools/call` to org endpoint

Related KB search does not replace human.ask for action proposals — use human.ask when you want classification + intent shaping.

Try it

SDK:

MCP client configuration (Cursor)

{
  "mcpServers": {
    "human": {
      "command": "npx",
      "args": ["-y", "@human/mcp"],
      "env": {
        "HUMAN_API_URL": "https://api.haio.run",
        "HUMAN_DELEGATION_TOKEN": ""
      }
    }
  }
}

In Agent mode, invoke human.ask with { "message": "…" }. For hosted Streamable HTTP, point at https://mcp.haio.run/mcp or your org host — see Hosted SSE.

Response fields to handle

Field	Meaning
`classification`	`question` · `context` · `intent` · `fuzzy`
`text`	Grounded answer or clarifying question
`citations`	KB / doc pointers when search ran
`intent_action`	Proposed next step — show to user; do not auto-execute irreversible ops

When classification is fuzzy, send another human.ask with the user's clarification in the same session_id.

Use cases

Claude Code doc lookup — human.ask for Canon-aware answers instead of hallucinating API shapes.

Intent shaping before execute — Companion returns intent_action; human approves; agent calls Tier 3 human.call.

Weekend noise reduction — natural-language policy question → Companion proposes mute rules → human confirms.

Public site proxy mode — browser widget uses server-side delegation; MCP uses the same /v1/companion/chat backend with a user-minted token (Embed Companion in Proxy Mode).

Security considerations

DO

Require companion:chat (and KB scopes) on the delegation

Pass session_id for multi-turn intent threads

Surface intent_action to humans before Tier 3 execution

DON'T

Do not expose delegation tokens in client-side HTML (use proxy mode for web)

Do not auto-run proposed actions without approval record

Do not substitute generic chat completions for human.ask — you lose classification + provenance hooks

Same route in the other SDKs

The TypeScript tab above is the contract. These calls hit that same route.