Skip to main content
HUMΛN

Momentum MCP Tools

Connect AI clients to your org's Momentum objects via the HUMΛN MCP capability mesh.

Canon: kb/22_humanos_orchestration_core.md · Mesh overview: MCP Capability Mesh

Endpoint

Every HUMΛN org exposes a hosted MCP endpoint:

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

Authenticate with a delegation token (Settings → MCP Access → New Token). Scope must include momentum CRUD and run permissions for your org.

Claude Desktop

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

Cursor

{
  "mcpServers": {
    "human": {
      "url": "https://acme.mcp.haio.run/mcp",
      "transport": "sse"
    }
  }
}

human.momentum.* tool surface

Tools are generated from OpenAPI x-mcp-tool annotations on momentum routes. Primary exposed tools:

Tool API Description
human.momentum.create POST /v1/momentum Create a Momentum object from goal, triggers, and policies
human.momentum.run POST /v1/momentum/:id/run Trigger an immediate run
human.momentum.list GET /v1/momentum List org Momentum objects (cursor pagination)
human.momentum.get GET /v1/momentum/:id Fetch a single object

Capability discovery/install routes are not exposed while Phase E resolver is stubbed (x-mcp-tool: expose: false). They flip to exposed when Plans 20+25 land.

Regenerate registry after API changes:

pnpm openapi:ai-update && pnpm openapi:generate && pnpm mcp:registry:generate
pnpm mcp:registry:check && pnpm mcp:doc-drift:check

Example tools/call payloads

Create

{
  "name": "human.momentum.create",
  "arguments": {
    "name": "Morning pipeline brief",
    "goal": "Summarize HubSpot pipeline changes and post to #sales",
    "triggers": [
      { "kind": "schedule", "cron": "0 8 * * 1-5", "timezone": "America/Los_Angeles" }
    ],
    "capability_families": ["briefing.prepare", "crm.read", "digest.deliver"],
    "preferred_connectors": ["hubspot", "slack"],
    "delivery": { "primary": "slack", "format": "immediate" },
    "policy": { "require_approval": false, "max_cost_per_run_usd": 1.5 }
  }
}

Run now

{
  "name": "human.momentum.run",
  "arguments": {
    "id": "mom_abc123"
  }
}

Path parameters are merged from the tool schema — use the id field your client exposes for :id routes.

Governance and scopes

  • Org isolation: All momentum routes require org context from the delegation JWT.
  • Human-in-the-loop: Objects with approval_policy.require_approval: true may return runs in awaiting_approval — the MCP client should surface that state, not retry blindly.
  • Rate limits: Run/pause/resume are capped at 60/min; CRUD at 1000/min. Respect X-RateLimit-* headers.
  • Provenance: Each run emits ledger receipts when provenance_policy.emit_receipts is true (default).

SDK equivalent (TypeScript)

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

const client = new HumanClient({ delegationToken: process.env.HUMAN_DELEGATION_TOKEN! });

const obj = await client.momentum
  .build('Watch competitor pricing pages')
  .every('every monday at 9am')
  .using(['web-capture'])
  .create();

await client.momentum.run(obj.id);

Reference

Topic Location
Getting started docs/guides/momentum-getting-started.md
Architecture docs/guides/momentum-deep-dive.md
Mesh overview docs/mcp-capability-mesh.md
Connect runbook docs/runbooks/mcp-server-connection.md
OpenAPI source apps/api/src/routes/momentum/index.ts

← All guides