MCP three-tier control ladder

Overview

HUMΛN MCP exposes one governed surface to AI clients (Cursor, Claude Code, Continue, Zed) with three tiers of control. Start at Tier 1 — human.ask — and drop down only when you need explicit parameters, raw API paths, or org-specific workflow tools.

The hosted Worker at https://mcp.haio.run (or https://{org_slug}.mcp.haio.run) is a transport + auth + scope-policy shell. Business logic lives at api.haio.run; the Worker dispatches JSON-RPC to real routes in @human/mcp/catalog and apps/mcp-worker/src/dispatcher.ts.

Why three tiers?

Tier	Tools	When to use
1 — Magic	`human.ask`, `human.companion.kb_search`	Natural language; Companion classifies, shapes intent, answers or proposes action
2 — Explicit	`human.intent`, `human.capability.discover`, catalog platform tools	You know the operation but want typed, scoped calls
3 — Mesh + REST	`human.call`, org workflow/agent tools from `GET /v1/mcp/tools`, `/v1/mcp/proxy` fallbacks	Execute with delegation + provenance; org capability graph

Think of it like: Tier 1 is asking a colleague; Tier 2 is opening the runbook; Tier 3 is calling the API yourself — with the same Passport delegation either way.

Fourth Law applies at every tier: when confidence is low, human.ask returns classification: "fuzzy" or an escalation path — it does not fake certainty.

Shipped surfaces

There is no fictional HumanMCP.invoke() namespace. Use:

Surface	Purpose
Hosted MCP	`https://mcp.haio.run/mcp` (Streamable HTTP) · `https://mcp.haio.run/sse` (legacy SSE)
Org MCP	`https://{org_slug}.mcp.haio.run/mcp`
Local stdio bridge	`npx @human/mcp` with `HUMAN_ORG_ENDPOINT`
Tier 1 flagship	`human.ask` → `POST /v1/companion/chat`
Tier 3 execution	`human.call` → `POST /v1/agents/call`
Org tool mesh	`GET /v1/mcp/tools` (Worker caches per session)

Implementation: apps/mcp-worker/src/dispatcher.ts, packages/mcp/src/catalog/execute-tool-route.ts.

Try it

Tier 1 — `human.ask` (hosted Streamable HTTP)

SDK:

Tier 2 — explicit intent + capability discovery

// tools/call → human.intent — compile a brief into a capability plan
await mcpToolsCall('human.intent', {
  brief: 'Reduce agent notification noise on weekends',
});

// tools/call → human.capability.discover
await mcpToolsCall('human.capability.discover', {
  query: 'invoice approval workflow',
});

Tier 3 — `human.call` with provenance

await mcpToolsCall('human.call', {
  capability: 'workforce.assign_task',
  input: {
    org_did: process.env.HUMAN_ORG_DID,
    title: 'Review Q3 invoice batch',
    required_capabilities: ['accounting'],
  },
});
// Dispatches to POST /v1/agents/call with delegation + risk gate

List what your token can see

curl -s -X POST 'https://mcp.haio.run/mcp' \
  -H "Authorization: Bearer $HUMAN_DELEGATION_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Org hosts merge platform catalog tools with org mesh tools from GET /v1/mcp/tools.

Use cases

Developer in Cursor — Tier 1 human.ask for Canon docs and scaffolding guidance; Tier 2 when you need human.canon.check; Tier 3 human.call to run an agent.
Claude Code on hosted MCP — OAuth PKCE to mint a session delegation, then Tier 1 for conversational work; drop to Tier 3 for irreversible actions that need explicit capability names.
Org automation — {slug}.mcp.haio.run exposes installed workflow and agent tools from the capability graph alongside platform primitives.
CI / headless — npx @human/mcp stdio bridge with a pre-minted delegation; skip Tier 1 streaming, call catalog tools directly.

Security considerations

DO

Start at Tier 1; escalate scope only when the task requires it

Mint minimal scopes (companion:chat, kb:read:public) for read-only exploration

Use org-scoped hosts when the delegation is org-bound

DON'T

Do not bypass delegation with raw API keys in MCP client configs

Do not treat human.ask as auto-execute — review intent_action proposals

Do not invent tool names; use tools/list or the platform registry