MCP & AGENTS

Build consent-first agents with hussh MCP.

The current developer lane is Agent Kai plus the hussh MCP. Start in UAT, discover the user's available scopes, request explicit consent, then read only the encrypted scoped export the user approved.

Open Kai UAT workflow Open @hushh/mcp

HCT tokens

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

Encrypted exports

Ciphertext and wrapped-key metadata only; the 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.

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 the 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 for scope discovery, consent requests, status checks, token validation, and scoped exports.

npm bridge

npx -y @hushh/mcp

Use the public launcher when the host 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 and export

Validate the HCT token, then retrieve the encrypted scoped export. The connector decrypts client-side.

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 first-party or internal flows.

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.