@aura-payments/mcp-server

Model Context Protocol server for Aura Payments. Drop it into Claude Desktop, Cursor, Continue, or any other MCP host and your AI agent can create escrows, manage agents, approve mandates, and check wallet balances natively, without writing HTTP boilerplate.

Install

npm install -g @aura-payments/mcp-server
# or invoke directly via npx (no install)
npx @aura-payments/mcp-server

Configure (Claude Desktop / Cursor / any MCP client)

Add this to your mcp.json (paths vary by host, e.g. ~/Library/Application Support/Claude/mcp.json for Claude Desktop on macOS, ~/.cursor/mcp.json for Cursor):

{
  "mcpServers": {
    "aura": {
      "command": "aura-mcp",
      "env": {
        "AURA_API_KEY": "pk_live_..."
      }
    }
  }
}

Get an API key at https://getaura.sh.

Optional env

| Variable | Default | Purpose | | ----------------------- | ----------------------------- | ---------------------------------------------------- | | AURA_API_KEY | (required) | Your platform API key (pk_live_* or pk_test_*) | | AURA_BASE_URL | https://tryaura.xyz/api | Override for self-hosted or staging deployments | | AURA_AUTO_IDEMPOTENCY | true | Auto-generate idempotency keys for POST/PUT requests |

Tools

| Tool | What it does | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | aura_create_escrow | Create a new escrow with payment splits across vendor/platform/seller wallets | | aura_get_escrow | Get the current state of an escrow | | aura_list_escrows | List escrows with state/sort/search filters | | aura_fund_escrow | Fund an escrow from the buyer wallet | | aura_release_escrow | Release a funded escrow to recipients per the splits | | aura_refund_escrow | Refund a funded escrow back to the buyer | | aura_create_agent | Create a new AI agent with a dedicated wallet and optional initial spending policy | | aura_list_agents | List agents (filter by status/type, paginated) | | aura_get_agent | Get a single agent by id | | aura_get_agent_balance | Get an agent's current USDC wallet balance (on-chain) | | aura_freeze_agent | Kill switch — pause the agent and cascade-reject every pending mandate it has in flight | | aura_unfreeze_agent | Resume a frozen agent | | aura_evaluate_policy | Run a hypothetical transaction through the policy engine without executing it | | aura_list_mandates | List operator mandates (defaults to status=pending — the inbox) | | aura_get_mandate | Get a single mandate by id | | aura_approve_mandate | Approve a pending mandate. Requires a precomputed HMAC decision signature (the LLM never sees the secret). | | aura_reject_mandate | Reject a pending mandate. Same signature scheme. | | aura_get_wallet_balance | Get any wallet's USDC balance |

Resources

| URI | Returns | | -------------------------------- | ------------------------------------------------------ | | aura://agents/{id} | Full agent record (status, wallet, type, etc.) | | aura://agents/{id}/balance | Current on-chain USDC balance | | aura://mandates/pending | The operator's inbox (50 most-urgent pending mandates) | | aura://mandates/{id} | Full mandate record (intent, status, decision history) |

Try it

Once configured, ask your AI agent:

"Using Aura, create a $50 USDC escrow on ARC, splitting 80% to vendor wallet <vendor-uuid> and 20% to platform wallet <platform-uuid>."

The agent should call aura_create_escrow and return the new escrow id.

"List all my pending mandates."

The agent should call aura_list_mandates (defaults to pending) and show the inbox.

Approving mandates from an LLM

aura_approve_mandate requires a precomputed HMAC-SHA256 signature over ${mandateId}:approve:${decidedAt}. The LLM should NOT compute this — the secret stays out of model context. Instead, use the Aura CLI (aura mandates approve <id>) or the mobile app to approve, and the LLM can confirm via aura_get_mandate that the decision landed.

If you want LLM-driven approval (e.g., for a fully autonomous ops agent), run a thin trusted shim alongside the MCP server that holds the secret and exposes a non-MCP signing endpoint. That's deliberately not bundled here.

Errors

Every tool catches errors and returns them as structured isError: true results so the LLM can read the message. The errorCode line tells the LLM what kind of error it is:

| errorCode | What it means | | ------------------- | ---------------------------------------------------------------------- | | CONFIG_ERROR | AURA_API_KEY missing or unreadable | | AUTH_ERROR | Key is invalid, revoked, or unauthorized for the requested resource | | NOT_FOUND | The escrow / agent / mandate doesn't exist (or isn't yours) | | VALIDATION_ERROR | Request body failed server-side validation | | RATE_LIMITED | Too many requests. Includes retryAfter when available | | TIMEOUT | Request exceeded the SDK timeout (default 30s) | | API_ERROR_<code> | Generic platform error (5xx etc.) |

License

MIT.