DocsBuildAPI ReferenceSDK Reference

HUMΛN MCP — Tools Reference

Canon: kb/10 §AI Internal Use, kb/13 §Foundational Principles, kb/22 §HumanOS, kb/101 §API Design Standards.

Surface: @human/mcp (npm) — local stdio for Cursor; https://{org-slug}.mcp.haio.run/mcp — hosted Streamable HTTP; /sse for event-stream clients.

This article is the canonical machine-readable index of every tool exposed by HUMΛN MCP, the scope it requires, the input schema, and an example call/response. Use it to construct minimal delegation tokens and to validate tool calls before you make them.

Tier 1 — Conversational (start here)

human.ask

Purpose: Ask the Companion anything. The single most useful tool — handles QUESTION, CONTEXT, and INTENT modes. Required scope: companion:chat Optional scope: kb:read:public (for grounded answers)

Input:

{ "text": "string", "session_id": "string?" }

Output:

{
  "classification": "question | intent | context | fuzzy",
  "text": "string",
  "intent_action": {
    "tool_id": "string",
    "params": {},
    "autonomy": "observe | propose | auto",
    "requires_approval": true,
    "reversible": true,
    "human_readable": "string",
    "consequence": "string",
    "provenance_scope": "string"
  },
  "citations": [{ "uri": "human://kb/...", "title": "string" }]
}

The intent_action block is present only when classification === "intent" and the brief is clear.

Purpose: Semantic search over the Canon corpus + delegated KB sources. Required scope: kb:read:public (Public corpus); kb:read:internal for Internal docs.

Input:

{ "query": "string", "limit": 10, "classification_filter": ["public", "internal"] }

Output:

{ "results": [{ "doc_id": "string", "title": "string", "snippet": "string", "score": 0.91, "classification": "public" }] }

Tier 2 — Platform primitives

human.intent

Purpose: Compile an intent brief into a capability resolution plan. Required scope: humanos:write (POST /v1/intent + compile; matches required-scope-policies)

Input:

{ "raw_input": "string", "source_surface": "control_plane | companion | workflow_designer | agent_builder", "modality": "text" }

Output:

{ "intent_id": "string", "plan": { "steps": [{ "capability_id": "string", "params": {} }] } }

human.companion.chat

Purpose: Multi-turn Companion session with persistent context. Required scope: companion:chat Same shape as human.ask but accepts and returns session_id for continuity.

human.capability.discover

Purpose: Find capabilities that match a description. Required scope: human_api:capability_graph:read (POST /v1/capabilities/query)

Input:

{ "query": "string", "intent_family": "string?", "min_confidence": 0.7 }

Tier 3 — Direct REST (escape hatch + power tools)

human.call

Purpose: Execute a capability with delegation, risk gate, and provenance. Required scope: Delegation must include human_api:agents:invoke (same as POST /v1/agents/call), plus whatever scopes the target capability and API enforce (often returned as required_scope on 403). There is no call:execute scope string — use the tool argument mode: "propose" vs "execute" (plan tier and risk gate still apply).

Input:

{ "tool_id": "string", "params": {}, "approval_id": "string?", "idempotency_key": "string?" }

Output: capability-specific. Always includes provenance_id.

Pending-approval flow:

{ "status": "pending_approval", "approval_id": "string", "approve_url": "https://console.haio.run/approvals/..." }

Other Tier 3 tools (12+, abbreviated)

Note: GET /v1/agents and GET /v1/agents/:id (used by human.agent.list / human.agent.get) accept human_api:agents:read or agents:read on the API so Command Plane session delegations work; the hosted Worker catalog still requires human_api:agents:read.

Tool Scope Purpose
human.agent.list human_api:agents:read List agents (API also accepts agents:read).
human.agent.get human_api:agents:read Get one agent (same bridge as list).
human.workflow.list humanos:read GET /v1/workflows — cursor list.
human.workflow.dag humanos:read GET /v1/workflows/:id/dag.
human.passport.list_devices human_api:passports:read List devices on a passport.
human.passport.list_delegations human_api:passports:read List delegations issued by a passport.
human.delegation.mint human_api:passports:write Mint a new delegation.
human.delegation.revoke human_api:passports:write Revoke a delegation.
human.signals.list signals:read Read pending signals.
human.signals.ack signals:write Acknowledge a signal.
human.events.emit events:emit Emit a custom event.
human.workforce.tasks.list workforce:read List workforce tasks.
human.workforce.task.create workforce:write Create a task.
human.workforce.task.complete workforce:write Complete a task.
human.kb.docs.list kb:read:* List KB docs (filtered by classification).
human.org.settings.get org:settings:read Read org settings.

Tier 4 — Admin (HUMΛN team only)

These tools are not registered unless the calling delegation has cloud:admin:* scopes. Other clients won't see them in the catalog.

Tool Scope Purpose
human.admin.billing_config.get cloud:admin:billing Read billing_config rows.
human.admin.billing_config.set cloud:admin:billing Update billing_config (audited).
human.admin.flush_cache cloud:admin:global Flush an in-memory cache key (matches API + Worker admin catalog).
human.admin.tenant.get cloud:admin:support Look up a tenant by id.
human.admin.tenant.suspend cloud:admin:global Suspend a tenant (high-risk; provenance + approval).

Resources (human://)

@human/mcp also exposes MCP resources for AI clients to browse (not just call):

URI Content Required scope
human://kb/{doc_id} Full KB doc body kb:read:* matching classification
human://schemas/{schema_name} OpenAPI component schemas kb:read:public

Prompts

Reusable prompt templates for AI clients:

Name Use Required scope
review-agent-manifest Walks an agent manifest review with the Companion. companion:chat
design-delegation-scope Helps an agent author scope a delegation token. companion:chat

Error shape

All errors are RFC 7807 application/problem+json:

{
  "type": "https://api.haio.run/errors/insufficient-scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This tool requires `human_api:agents:invoke` (and capability scopes…). Your delegation has [companion:chat, kb:read:public].",
  "remediation": "Mint a new delegation with the missing scope, or use Tier 1 `human.ask` to surface a proposal instead."
}

The remediation field tells your client what to do next. Always read it.

← All guides