MCP & AGENTS

Connect OpenClaw, Hermes, and external agents with hussh MCP.

Bring OpenClaw, Hermes Agent, or any external MCP agent to a user's One PKM. Discover available scopes, request explicit consent for read or write access, then import only the approved encrypted export or continue with approved tool calls.

Open @hushh/mcp

Get your developer token

Sign in once to mint a personal token and copy a ready-to-paste MCP URL.

The docs stay open to everyone. Sign in only when you want a personal developer token tied to your hussh account.

HCT tokens

Signed, time-limited consent tokens with explicit scope and revocation checks.

Encrypted exports

Ciphertext and wrapped-key metadata only; OpenClaw, Hermes, or your external connector decrypts client-side.

Dynamic scopes

Scopes are discovered per user from PKM metadata instead of hardcoded globally.

Zero-knowledge

The server stores encrypted personal data and enforces consent before access.

OPENCLAW / HERMES

One connection path for every external agent

OpenClaw and Hermes are first-class ways to connect outside agent infrastructure to One, but the protocol is not locked to either name. Any external MCP agent can follow the same steps: discover PKM scopes, ask for consent, wait for the user, then import or write back only inside the approved grant.

OpenClaw connector

Point OpenClaw at the remote MCP URL or REST API so it can discover a user's live One PKM scopes before any data moves.

Hermes Agent

Use Hermes as the consent messenger: every external tool call becomes a clear request inside One with purpose, scope, expiry, and receipt.

Any external agent

If you are not using OpenClaw or Hermes, follow the same contract directly from your agent host: discover, request, wait, validate, then import or act.

Direct setup steps

01

Mint a developer token and connect OpenClaw, Hermes Agent, or your own agent host through Remote MCP, REST, or the npm bridge.

02

Call discover_user_domains so the agent sees the user's current PKM scopes instead of guessing from a static menu.

03

Call request_consent with the narrow read or write scope, purpose, expiry, timeout, and connector key-wrapping metadata.

04

After One approval, validate the HCT token, retrieve the encrypted scoped export for import, or keep write-capable tool calls inside the approved scope.

RUNTIME MODES

Three ways to integrate

Pick the host shape first. Remote MCP is the cleanest path for agent hosts, REST is the direct application contract, and the npm bridge keeps stdio-only clients on the same protocol.

Remote MCP

/mcp/?token=<developer-token>

Use this when OpenClaw, Hermes Agent, or any external agent host supports HTTP MCP. Keep the full URL secret because the token rides with the request.

REST API

https://api.uat.hushh.ai/api/v1

Use versioned endpoints when your OpenClaw/Hermes controller wants direct scope discovery, consent requests, status checks, token validation, and scoped exports.

npm bridge

npx -y @hushh/mcp

Use the public launcher when an external agent still expects a local stdio process instead of remote MCP.

CONSENT FLOW

Discover, request, approve, export

01

Discover user domains

Call discover_user_domains or GET /api/v1/user-scopes/{user_id}. Scopes are dynamic and come from the user's indexed PKM.

02

Request a specific scope

Ask for one discovered scope with a transparent reason, expiry, timeout, and connector key-wrapping metadata.

03

Wait for approval

The user approves or denies inside the hussh surface. Pending requests can be checked by request id, user, and scope.

04

Validate, import, or write back

Validate the HCT token, then retrieve the encrypted scoped export for import. For approved write-capable flows, keep every tool call inside the accepted scope.

SCOPE MODEL

Scopes are runtime facts, not a static menu

Always discover first. A broader active grant can satisfy a narrower request, but a narrower grant never silently upgrades to a broader parent scope.

pkm.read

Full PKM read access for approved first-party or internal flows.

pkm.write

Write access for approved One PKM update flows. External agents should request the narrowest write scope exposed by discovery.

attr.{domain}.*

One discovered domain, such as attr.financial.* or attr.food.*.

attr.{domain}.{subintent}.*

A narrower branch when PKM metadata exposes subintents.

MCP TOOLS

The public consent tool surface

https://api.uat.hushh.ai/mcp/?token=<developer-token>

list_scopes

Static reference for canonical scope patterns and discovery guidance.

discover_user_domains

Resolve user domains and the exact scope strings currently available.

request_consent

Create or reuse a scoped consent request with expiry and connector metadata.

check_consent_status

Poll a pending request until it is granted or denied.

validate_token

Verify HCT signature, expiry, revocation, and optional expected scope.

get_encrypted_scoped_export

Return ciphertext plus wrapped-key metadata for approved scoped access.