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?

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:

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

Try it

Tier 1 — human.ask (hosted Streamable HTTP)

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

See also

Companion as MCP tool — Tier 1 deep dive

Org MCP endpoint — {org}.mcp.haio.run

Hosted SSE & Streamable HTTP — /mcp, /sse, /messages

OAuth PKCE for MCP — browser consent → delegation JWT

Community: Getting Started with HUMΛN MCP

Guide: /docs/guides/mcp-integration

Same route in the other SDKs

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