@aroha-sdk/mcp-server
v1.0.0 · new

MCP Server

A standalone MCP stdio server that gives any MCP-compatible AI assistant or autonomous agent framework access to every vendor registered on the Aroha Hub. Five tools. One config block. No code required.

Installation

The config block is identical across all MCP clients — only the file path differs.

MCP config blocksame for all clients
{
  "mcpServers": {
    "aroha": {
      "command": "npx",
      "args": ["-y", "@aroha-sdk/mcp-server"],
      "env": {
        "AROHA_API_KEY": "sk-aroha-..."
      }
    }
  }
}
Client
Config file path
Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json (macOS) %APPDATA%\Claude\claude_desktop_config.json (Windows)
Cursor
~/.cursor/mcp.json
Windsurf
~/.codeium/windsurf/mcp_config.json
Cline (VS Code)
VS Code settings → Cline MCP Servers panel
Zed
~/.config/zed/settings.json (under context_servers)
Any stdio client
AROHA_API_KEY=sk-aroha-... npx @aroha-sdk/mcp-server
Autonomous agent frameworksprogrammatic

Hermes Agent · ZeroClaw — @aroha-sdk/hermes-bridge

import { createHermesBridge } from "@aroha-sdk/hermes-bridge";

const aroha = createHermesBridge({ apiKey: process.env.AROHA_API_KEY });
// aroha_discover, aroha_call, aroha_issue_task_mandate,
// aroha_issue_spending_mandate, aroha_get_receipt registered as tools
await agent.use(aroha);

OpenClaw · any MCP-native framework

Frameworks that speak MCP natively (OpenClaw, ZeroClaw stdio, LangChain MCP adapter) use the same JSON config block above — no bridge package needed.

LangChain · CrewAI · AutoGen — aroha.bridges (Python)

from aroha.bridges import ArohaToolkit

toolkit = ArohaToolkit(api_key=os.environ["AROHA_API_KEY"])
tools = toolkit.get_tools()
# [aroha_discover, aroha_call, aroha_issue_task_mandate, ...]

# Drop into any LangChain / CrewAI / AutoGen agent
agent = initialize_agent(tools, llm, agent=AgentType.OPENAI_FUNCTIONS)

Environment variables

Variable
Required
Description
AROHA_API_KEY
required
Your Aroha Hub API key. Get one from Studio → API Keys.
AROHA_REGISTRY_URL
optional
Override the Hub registry URL. Defaults to the production registry.

Tools reference

Five tools are exposed to the MCP client. Your AI assistant or agent framework can call them directly.

aroha_discoverread-only

Search the Aroha Hub registry for agents that can perform a capability. Returns agent DIDs, names, registered capabilities, and reputation scores.

Parameters

capabilitystring?Capability ID to search for — e.g. "book-flight", "check-balance", "research"
querystring?Free-text search against agent name or description

Example

// Your AI assistant calls this automatically when you ask it to find an agent
aroha_discover({ capability: "book-flight" })

// Returns:
[
  {
    "did": "did:aroha:airnz:booking",
    "name": "Air NZ Booking Agent",
    "capabilities": ["book-flight", "check-availability", "get-booking-status"],
    "reputation": 0.97,
    "endpoint": "https://agents.airnz.co.nz/aroha/v1"
  }
]
aroha_calltransacts

Call a vendor agent on the Hub. Automatically issues a spend-limited mandate. Returns a receipt ID for audit. Use aroha_discover first to find the agentDid.

Parameters

agentDidstringDID of the vendor agent (from aroha_discover)
capabilitystringCapability to invoke
paramsobjectParameters to pass to the capability
spendLimitUsdnumber?Max spend in USD (default 0 — for free/read capabilities)
purposestring?Human-readable reason (appears in audit trail)
taskDescriptionstring?Description of the delegated task

Example

aroha_call({
  agentDid:      "did:aroha:airnz:booking",
  capability:    "book-flight",
  params:        { from: "AKL", to: "SYD", date: "2026-08-15", passengers: 1 },
  spendLimitUsd: 600,
  purpose:       "One-way AKL→SYD for August trip"
})

// Returns:
{
  "success": true,
  "result": { "bookingRef": "NZ8821", "total": 389.99, "seat": "14A" },
  "receiptId": "rcpt-aroha-mcp-1752393600-x7k2p",
  "durationMs": 1240
}
aroha_issue_task_mandatemandate

Issue a task mandate authorising a vendor agent to perform specific capabilities within explicit resource limits. Use this for research, drafting, scheduling, or any non-monetary delegation.

Parameters

agentDidstringDID of the agent to authorise
allowedstring[]List of capability IDs the agent may invoke
blockedstring[]?Capability IDs to explicitly deny
actionLimitsobject?Max invocations per capability: { "send-email": 3 }
reversibleOnlyboolean?Block all irreversible capabilities when true
humanGatesstring[]?Capabilities requiring human approval before execution
maxLlmTokensnumber?Max LLM tokens the agent may consume
maxWebRequestsnumber?Max outbound HTTP requests
ttlMinutesnumber?Mandate expiry in minutes (default: 60)

Example

aroha_issue_task_mandate({
  agentDid:       "did:aroha:vendor:researcher",
  allowed:        ["research", "web-search", "web-read", "summarise"],
  reversibleOnly: true,        // no sends or publishes
  actionLimits:   { "web-search": 20 },
  maxLlmTokens:   50000,
  ttlMinutes:     30,
})

// Returns the mandate token + summary:
{
  "mandateId": "task-mandate-1752393600-abc123",
  "summary": "Task mandate issued to did:aroha:vendor:researcher",
  "allowed": ["research", "web-search", "web-read", "summarise"],
  "constraints": { "reversibleOnly": true, "actionLimits": { "web-search": 20 } },
  "validUntil": "2026-07-13T12:30:00Z"
}
aroha_issue_spending_mandatemandate

Issue a monetary spending mandate authorising a vendor agent to charge up to a specified amount. The limit is cryptographically enforced — the vendor cannot exceed it.

Parameters

agentDidstringDID of the agent to authorise
capabilitystringThe specific capability this spend is authorised for
spendLimitUsdnumberMaximum spend in USD
allowedMerchantsstring[]?Optional: restrict to specific merchant DIDs
ttlMinutesnumber?Mandate expiry in minutes (default: 10)

Example

aroha_issue_spending_mandate({
  agentDid:      "did:aroha:airnz:booking",
  capability:    "book-flight",
  spendLimitUsd: 600,
  ttlMinutes:    10,
})

// Returns:
{
  "mandateId": "spend-mandate-1752393600-xyz789",
  "summary": "Spending mandate: up to $600 USD for book-flight",
  "spendLimitUsd": 600,
  "validUntil": "2026-07-13T11:40:00Z"
}
aroha_get_receiptread-only

Retrieve the task receipt for a completed aroha_call. Shows every action taken, resources consumed, mandate checks, and outputs produced.

Parameters

receiptIdstringReceipt ID returned by aroha_call

Example

aroha_get_receipt({ receiptId: "rcpt-aroha-mcp-1752393600-x7k2p" })

// Returns:
{
  "receiptId": "rcpt-aroha-mcp-1752393600-x7k2p",
  "mandateId": "mandate-aroha-mcp-1752393600-x7k2p",
  "executedByDid": "did:aroha:airnz:booking",
  "status": "complete",
  "actions": [{ "capability": "book-flight", "status": "success", "durationMs": 1240 }],
  "consumed": { "webRequests": 1, "wallClockMs": 1240 },
  "mandateBoundsCheck": { "withinBounds": true, "violations": [] },
  "outputs": [{ "type": "data", "summary": "book-flight completed successfully" }]
}

Worked example — book a flight

Once the MCP server is configured in any supported client, a conversation like this works end-to-end:

AI assistant conversationworks in Claude, Cursor, Windsurf, Hermes, and any MCP client
Book me the cheapest flight from Auckland to Sydney on August 15th, spend no more than $600.
AI
I'll discover airline agents on the Aroha Hub, then book within your $600 limit.
fn
aroha_discover({ capability: "book-flight" }) → 3 agents found
fn
aroha_call({ agentDid: "did:aroha:airnz:booking", capability: "check-availability", params: { from: "AKL", to: "SYD", date: "2026-08-15" } })
fn
aroha_call({ agentDid: "did:aroha:airnz:booking", capability: "book-flight", params: { ... }, spendLimitUsd: 600 }) → NZ8821 · $389.99
AI
Done! Booked NZ821 on August 15th, Auckland → Sydney. Seat 14A. Total charged: $389.99 (well within your $600 limit). Booking ref: NZ8821.

Receipts are session-scoped

Task receipts are stored in the MCP server process memory. They persist for the lifetime of the server process only — not across restarts. For durable audit logs, persist the receipt returned by aroha_call to your own database, or use @aroha-sdk/audit for append-only hash-chained logging.

← Task MandatesPersonal agent guide →