Skip to main content
HUMΛN

Companion as MCP tool

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": "<delegation with companion:chat>"
      }
    }
  }
}

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

  1. Claude Code doc lookup — human.ask for Canon-aware answers instead of hallucinating API shapes.
  2. Intent shaping before execute — Companion returns intent_action; human approves; agent calls Tier 3 human.call.
  3. Weekend noise reduction — natural-language policy question → Companion proposes mute rules → human confirms.
  4. 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

See also

← All patterns