@aroha-sdk/mcp-server

MCP stdio server that exposes the Aroha Hub to Claude Desktop and any other MCP-compatible personal agent. Once configured, Claude can search the Hub for registered vendor agents, issue task and spending mandates, call those agents directly, and retrieve the full audit receipt — all through natural conversation, without any corporate agreement or bespoke integration.

Installation — Claude Desktop

Add the following block to your claude_desktop_config.json (on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "aroha": {
      "command": "npx",
      "args": ["-y", "@aroha-sdk/mcp-server"],
      "env": {
        "AROHA_API_KEY": "sk-aroha-..."
      }
    }
  }
}

Restart Claude Desktop. The five aroha_* tools will appear in the tool list automatically.

Optional environment variables

| Variable | Default | Purpose | |---|---|---| | AROHA_API_KEY | "" | Bearer token for authenticated Hub calls | | AROHA_REGISTRY_URL | https://aroha-registry.aroha-labs.workers.dev | Override the Hub registry endpoint |

Tools

aroha_discover

Search the Aroha Hub registry for agents by capability ID or free-text query. Returns up to 10 matching agents with their DIDs, names, capabilities, reputation scores, and endpoints.

aroha_discover(capability?: string, query?: string)

aroha_call

Call a vendor agent. Automatically packages a spending mandate intent in the request so the agent knows its authorised budget. Returns a receiptId for later audit retrieval.

aroha_call(agentDid, capability, params, spendLimitUsd?, purpose?, taskDescription?)

aroha_issue_task_mandate

Issue a fine-grained task mandate specifying exactly which capabilities the agent may invoke, how many times, whether they must be reversible, and which require a human gate before execution.

aroha_issue_task_mandate(agentDid, allowed[], blocked[]?, actionLimits?, reversibleOnly?, humanGates[]?, maxLlmTokens?, maxWebRequests?, ttlMinutes?)

aroha_issue_spending_mandate

Issue a monetary spending mandate capping the agent at a specified USD amount for a single capability. Optionally restrict to a list of approved merchant DIDs.

aroha_issue_spending_mandate(agentDid, capability, spendLimitUsd, allowedMerchants[]?, ttlMinutes?)

aroha_get_receipt

Retrieve the task receipt for a completed aroha_call. Shows the full audit trail: actions taken, resources consumed, mandate bounds check, and agent outputs.

aroha_get_receipt(receiptId)

Worked example — Book a flight via Air NZ agent

User: Find an Air New Zealand agent that can book flights, then book me on the cheapest Auckland to Wellington flight tomorrow.

Step 1 — Claude calls aroha_discover

{ "capability": "book-flight", "query": "Air New Zealand" }

Result (truncated):

[{
  "did": "did:aroha:airnz-booking-agent",
  "name": "Air NZ Booking Agent",
  "capabilities": ["book-flight", "check-flight-status", "cancel-booking"],
  "reputation": 4.9,
  "endpoint": "https://agents.airnz.co.nz/aroha"
}]

Step 2 — Claude calls aroha_issue_spending_mandate

{
  "agentDid": "did:aroha:airnz-booking-agent",
  "capability": "book-flight",
  "spendLimitUsd": 150,
  "ttlMinutes": 10
}

Result:

{
  "mandateId": "spend-mandate-1749123456-abc123",
  "summary": "Spending mandate: up to $150 USD for book-flight with did:aroha:airnz-booking-agent",
  "validUntil": "2026-07-13T09:30:00.000Z"
}

Step 3 — Claude calls aroha_call

{
  "agentDid": "did:aroha:airnz-booking-agent",
  "capability": "book-flight",
  "params": {
    "origin": "AKL",
    "destination": "WLG",
    "date": "2026-07-14",
    "cabin": "economy",
    "passengers": 1,
    "preferCheapest": true
  },
  "spendLimitUsd": 150,
  "purpose": "Book cheapest AKL-WLG flight for user"
}

Result:

{
  "success": true,
  "result": {
    "bookingRef": "NZ-X9K3M",
    "flight": "NZ409",
    "departure": "07:00",
    "arrival": "08:05",
    "fareUsd": 89.00,
    "confirmationEmail": "sent"
  },
  "receiptId": "rcpt-aroha-mcp-1749123456-xyz789",
  "durationMs": 1243
}

Step 4 — Retrieve audit receipt

{ "receiptId": "rcpt-aroha-mcp-1749123456-xyz789" }

The receipt confirms the agent stayed within the $150 mandate, made 1 web request, and produced a confirmed booking reference.

License

MIT — Copyright (c) 2026 Aroha Labs