Skip to content
HumanAuth Docs

HARP in 5 Minutes

Get HARP running end-to-end: install the CLI, pair your phone, wire up your agent, and send your first authorization. About 5 minutes total.

Prerequisites

Section titled “Prerequisites”
  • Node.js 20+ installed
  • HARP App on your phone (iOS App Store / Google Play)
  • An MCP-compatible agent (Claude Code, Cursor, etc.) or any Node.js project

Install and Pair

Section titled “Install and Pair”
Terminal window
npx @humanauth/cli pair --name "my-laptop"

A QR code appears in your terminal:

HARP Pairing QR Code
=====================


  Scan this QR code with the HARP app on your phone.


  ████████████████████████████████
  ████ ▄▄▄▄▄ █ ▄█▀█ █ ▄▄▄▄▄ ████
  ...


  Platform:  my-laptop
  Relay:     https://relay.humanauth.ai
  Expires:   5 minutes


  Waiting for app to complete pairing...
  1. Open the HARP app on your phone
  2. Tap Scan to Pair
  3. Point your camera at the QR code
  4. Confirm the pairing on your phone

When pairing succeeds you will see:

Pairing complete!


  pair_id:  pair_a1b2c3d4e5f6
  name:     my-laptop
  relay:    https://relay.humanauth.ai


  Pairing saved to ~/.harp/pairings/my-laptop.json

Configure Your Agent

Section titled “Configure Your Agent”

Pick the integration that fits your setup:

Add HARP to your MCP client config. For Claude Code, edit ~/.claude/settings.json:

{
  "mcpServers": {
    "harp": {
      "command": "npx",
      "args": ["@humanauth/mcp"]
    }
  }
}

That is it. Your agent now has three tools it can call depending on the intent: human_authorize (needs authorization), human_collect (needs input), and human_inform (notify only). Example human_authorize call:

{
  "tool": "human_authorize",
  "pair_id": "pair_a1b2c3d4e5f6",
  "action": "bash_execute",
  "description": "Delete temporary build files",
  "reasoning": "Build cache is 4GB and disk is 92% full",
  "severity": "medium",
  "ttl": 300
}

Send Your First Request

Section titled “Send Your First Request”

If you are using MCP, your agent calls human_authorize, human_collect, or human_inform automatically based on the intent. To test a manual authorization request:

Terminal window
humanauth request \
  --name "my-laptop" \
  --action "test_approval" \
  --description "This is a test authorization request" \
  --ttl 120

Your phone buzzes. Open the notification, review the request, and tap Approve (with biometric auth) or Deny.

Response received!


  decision:   approved
  timestamp:  2026-04-12T10:30:45Z
  signature:  verified

What Happens Under the Hood

Section titled “What Happens Under the Hood”
  1. Encrypt — The SDK encrypts the request context (one of three intent types: authorize, collect, or inform) with XChaCha20-Poly1305 using the shared key from pairing
  2. Route — The encrypted envelope is sent to the relay at relay.humanauth.ai, which forwards it without ever seeing the plaintext
  3. Notify — The relay sends a push notification to your phone
  4. Review — The HARP app decrypts the request and shows you the full action details
  5. Authenticate — You approve or deny with Face ID or fingerprint
  6. Sign and respond — The app signs the response with your Ed25519 key and encrypts it back
  7. Verify — The SDK receives the encrypted response, verifies the signature, and returns the decision

Both sides keep a full plaintext audit log locally. The relay only ever sees encrypted blobs.

Next Steps

Section titled “Next Steps”