DocsBuildAPI ReferenceSDK Reference

MCP Integration

Every HUMΛN org is an MCP server. Workflows, agents, installed Capability Packs, and connected external servers appear in tools/list and execute through the same governance stack as the REST API — identity, delegation scopes, and provenance on every call. Install a bundle and its tools show up automatically: no per-bundle integration code, and no difference between first-party and third-party capabilities.

This guide covers connecting a client, driving the mesh from the CLI and SDK, and the Canon-as-Code tools that let any MCP client validate governed documentation.

Connect over Streamable HTTP

MCP clients connect with Streamable HTTP at:

https://{org-slug}.mcp.haio.run/mcp

Authenticate with a delegation JWT or hpat_ token:

{
  "mcpServers": {
    "human": {
      "url": "https://acme.mcp.haio.run/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_DELEGATION_TOKEN"
      }
    }
  }
}

Clients that require event-stream transport can use GET /sse and POST /messages on the same host. First connection without a Bearer token triggers OAuth/PKCE in your browser — approve the requested scopes in the HUMΛN Console and the client receives a session-scoped delegation. Per-client walkthroughs (Cursor, Claude Code, Continue, Zed): Hosted MCP quickstart.

Drive the mesh from the CLI

human login
human mcp endpoint
human mcp list-tools
human mcp call-tool workflow.wf_123 --input '{"amount": 500}'
human mcp connect https://remote.example.com/mcp
human mcp config
human mcp config --reveal-token   # Print snippet with real bearer (stderr warning)

human mcp call-tool <tool_name> [--input <json>] invokes a mesh tool by the same name list-tools returns (for example workflow.<id>, agent.<org-agent-id>, human.*). Default --input is {}.

Token resolution for the local server

When you launch the MCP server locally (for example npx @human/mcp), credentials resolve in this order:

  1. HUMAN_DELEGATION_TOKEN environment variable (highest priority)
  2. ~/.human/config.yaml — written by human login (no env var needed if you already logged in)
  3. Interactive login — when stdin/stdout is a TTY and no token is found, the server runs the same loopback/device flow as human login
  4. Non-TTY failure — CI and headless hosts must set HUMAN_DELEGATION_TOKEN or pre-run human login

Use human mcp config --reveal-token to copy a ready-made client JSON with your real bearer. Never commit that output.

Drive the mesh from the SDK

import { HumanClient } from '@human/sdk';

const client = new HumanClient({ delegationToken: process.env.HUMAN_DELEGATION_TOKEN! });
const { tools } = await client.mcp.listTools();
await client.mcp.callTool('workflow.invoice-approval', { amount: 500 });
const endpoint = await client.mcp.getOrgEndpoint();

Mesh execution

Mesh tool names (workflow.*, agent.*, human.*, external tool names) resolve directly — no capability:// prefix required in MCP clients. Every call is validated against the session's delegation scopes before it executes, and every execution lands in provenance.

LiveSession tools

Live interaction uses the same MCP endpoint with human.live.* tools (parity with the human live CLI):

MCP tool CLI equivalent
human.live.session.create human live start
human.live.session.get human live status
human.live.session.close human live stop
human.live.session.override human live override
human.live.intent.propose human live test-intent

Requires delegation scopes live:read:session and live:write:session.

Canon tools — governed docs from any MCP client

The developer tools pack ships two human.canon.* tools, so AI clients can validate and scaffold Canon-as-Code documentation without leaving the editor:

Tool Purpose
human.canon.check Validate Canon-as-Code frontmatter and doc structure for markdown files under a directory
human.canon.scaffold_doc Scaffold a Canon-compliant markdown document with frontmatter and required section stubs

Example calls:

{ "name": "human.canon.check", "arguments": { "path": "docs", "requireNewFields": false } }

{
  "name": "human.canon.scaffold_doc",
  "arguments": { "docType": "Spec", "id": "42_payment_flows", "title": "Payment Flows" }
}

human.canon.check returns structured pass/fail per file; human.canon.scaffold_doc returns compliant markdown ready to save. Both are available from the hosted endpoint and the local @human/mcp server with the same config shown in the connection section — the tools appear in tools/list once the developer tools pack is installed for your org.

Go deeper

The MCP series in the community covers the design behind the surface:

Reference

← All guides