Desktop guide · AI agents

AI agents (MCP)

Give an AI agent on your computer, such as Claude Code, Claude Desktop or Cursor, its own wallet. It can check the balance, pay your contacts, ask to be paid and follow those payments, inside limits that SpiffyVault checks before every payment. It never sees your other wallets, your keys or your recovery phrase.

Agent access is in the desktop app only, and it is off until you turn it on. It speaks the Model Context Protocol (MCP), so any agent that supports MCP servers can use it.

How it works

• One wallet. You set aside an Agent wallet and put in only what the agent needs. Agents can see and spend that wallet only.
• On this computer only. SpiffyVault listens at http://127.0.0.1:47321/mcp. Other computers cannot reach it, and web pages in your browser are refused.
• A key per agent. Each agent you add gets its own access key, kept in your system keychain. Revoke it and that agent is out at once.
• Your limits, checked by SpiffyVault. The most per payment, per day, per week and per hour, who the agent may pay, and when you are asked first. The agent cannot change them.
• Everything logged. Every call shows under Agents › Activity, with the rule that allowed, asked about or refused each payment.
• SpiffyVault must be open. The agent reaches the wallet only while the app runs with agent access on.

Set up in five steps

1. Make an Agent wallet

Click New wallet…, give it a name, choose Agent under What is it for? and click Create Wallet. To turn a wallet you already have into one, open it and choose Wallet kind: … in its More (⋯) menu.

The limits bind agents only. You spend an Agent wallet like any other, and its recovery phrase restores it as a normal wallet.

2. Turn on agent access

Open Settings › Agent access (MCP) and turn on the switch. The Agents section appears in the sidebar.

3. Choose the agent's wallet and fund it

Under Agents may use, choose your Agent wallet. Only Agent wallets are listed. Then click Move money in… to move some coins into it from another of your wallets.

Keep the Agent wallet small and top it up when needed. The wallet's balance is the most an agent could ever spend.

4. Add an agent

Click Add an agent…, type a name (for example Claude Code), choose its access level and click Add. The Connect dialog opens.

5. Connect it

Choose your agent under Which agent? and follow the steps shown: see Connect your agent. Then ask it: "What is my SpiffyVault balance?"

Check and change the limits before the agent pays anyone: see Limits.

Connect your agent

The Connect dialog shows the exact steps for each agent, with your access key filled in. Copy always copies the full key, although the screen hides most of it. To see the steps again later, click Connect… on the agent's row. Below, <key> stands for that agent's access key.

Claude Desktop (easiest)

1. Click Download SpiffyVault.mcpb and save the file.
2. Click Open it, or double-click SpiffyVault.mcpb. Claude Desktop shows Install SpiffyVault: click Install.
3. Ask Claude: "What is my SpiffyVault balance?"

Claude Desktop runs the extension with the Node.js it ships, so there is nothing else to install.

The .mcpb file holds the agent's access key. Do not share it, and delete it once Claude has installed it.

Claude Code

Run this in a terminal, then start a new session. /mcp lists the server.

claude mcp add --transport http spiffyvault http://127.0.0.1:47321/mcp --header "Authorization: Bearer <key>"

Cursor

Add this to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project), then restart Cursor.

{
  "mcpServers": {
    "spiffyvault": {
      "url": "http://127.0.0.1:47321/mcp",
      "headers": { "Authorization": "Bearer <key>" }
    }
  }
}

VS Code (Copilot)

Add this to .vscode/mcp.json in your project, or to your user MCP settings.

{
  "servers": {
    "spiffyvault": {
      "type": "http",
      "url": "http://127.0.0.1:47321/mcp",
      "headers": { "Authorization": "Bearer <key>" }
    }
  }
}

Windsurf

Add this to ~/.codeium/windsurf/mcp_config.json.

{
  "mcpServers": {
    "spiffyvault": {
      "serverUrl": "http://127.0.0.1:47321/mcp",
      "headers": { "Authorization": "Bearer <key>" }
    }
  }
}

Gemini CLI

Add this to ~/.gemini/settings.json.

{
  "mcpServers": {
    "spiffyvault": {
      "httpUrl": "http://127.0.0.1:47321/mcp",
      "headers": { "Authorization": "Bearer <key>" }
    }
  }
}

Any other MCP agent

Add a server that uses Streamable HTTP:

For an agent that can only start local programs, use the open-source mcp-remote bridge (it needs Node.js). For example, in Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "spiffyvault": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:47321/mcp",
               "--header", "Authorization:${SPIFFYVAULT_AUTH}"],
      "env": { "SPIFFYVAULT_AUTH": "Bearer <key>" }
    }
  }
}

Access levels

Each agent has one level. Change it at any time with the Read / Prepare / Pay control on the agent's row. A new agent starts at Prepare.

Limits

Set them under Limits in Settings › Agent access (MCP), then click Save limits. They apply to every agent paying from the Agent wallet, and never to your own payments.

Who it may pay:

• Only my contacts (the default);
• My contacts and payment keys I approve: a payment to a new BRC-100 payment key asks you first, and a yes approves that key for later;
• Anyone (Advanced).

Agents can never pay a plain BSV address. They pay contacts by name, SpiffyVault payment links and BRC-100 payment keys.

Ask me first: Above an amount (default on, 5,000 sats), and The first payment to anyone (default on).

In what order SpiffyVault checks

Refusals come before questions. SpiffyVault refuses a payment that breaks a limit (single payment, day, week, per hour, who it may pay) or that the wallet cannot cover. Only a payment that passes all of them can come to you as a question. Anything else is paid at once.

When the agent asks you

A payment that needs your yes opens a dialog over SpiffyVault, titled "<agent> asks to pay". It shows the payee, the amount, the agent's reason, the note the payee will see, and how much of your day, week and hour the payment would use.

• Pay … sats: SpiffyVault checks the limits again, then pays.
• No: nothing is paid.
• No, and pause all agents: nothing is paid, and every agent call is refused until you resume.
• Decide later: closes the dialog. The payment waits under Agents › Requests.

You have 10 minutes. No answer counts as No. The agent does not wait all that time: after 30 seconds (at most 55, if it asks) it is told the payment waits for you, and it can check again later with get_payment or list_waiting_payments. A count on the toolbar's agent button shows how many payments wait for you.

Drafts

An agent with Prepare access fills in a payment for you: who, how much, and why. Nothing is paid until you send it.

1. SpiffyVault shows "<agent> prepared a payment". Click Review, or open Agents › Requests.
2. Under Needs you, click Review & send, or Decline.

You send a draft yourself, so the limits do not apply. A draft waits 24 hours.

Getting paid

An agent can ask to be paid: it makes a payment request, a SpiffyVault payment link with a short reference such as K7Q2M9XD, an optional amount and note, and an expiry (24 hours by default, from 5 minutes to 30 days). The agent gives the link to the payer and follows the request until it is paid.

• The money goes into the Agent wallet. When a SpiffyVault user pays the link, their app puts ref K7Q2M9XD in the payment's note, and your SpiffyVault sends the payment into the request's wallet. This works when your computer is offline too: the payment waits in your mailbox.
• The link does not name your wallet. It holds only the reference. Your SpiffyVault keeps which wallet each reference belongs to.
• Paying another way. A contact can also pay you with a normal payment and type ref K7Q2M9XD in the note.
• Only the reference counts. A payment without the reference never counts toward a request, even if the amount is the same.
• Part payments show as "x of y in" until the request is paid in full.
• Late payments. A request past its time, or cancelled, can still be paid: it then shows as Paid late.

A request is Open, Paid, Expired or Cancelled. If a payment with the reference arrives in another of your wallets (for example from an older app), the request still counts it and shows which wallet it went into.

Agents › Requests

What your agents ask you to decide, and the payments they asked others to make.

• Summary: what needs you, the sats still asked in open requests, and what came in over the last 7 days.
• Needs you: payments waiting for your yes, and drafts, oldest first, with Approve & pay, Review & send and Decline.
• Payment requests: a table with tabs All, Open, Paid and Expired. Each row has Copy link or View payment, and a menu with Show QR and Cancel request.

Click a row for its detail: the link and a large QR code, a timeline from the request to the payment, and its facts. Press Esc or click All requests to go back.

Agents › Activity

Every call your agents made to the Agent wallet, in plain words.

• Agent spending vs your limits: bars for the last 24 hours, the last 7 days and this hour. A bar turns amber at 80% and red at 100%.
• Filters: by agent, by period, and All, Money, Needs you or Refused. Reads by one agent on one day are grouped; tick Show each read to see them one by one.
• Rule check: click an entry to see the agent's reason and the rule that decided it, for example "Within your limits: 12,000 of 50,000 sats in 24 hours…" or "Refused: Over the single-payment limit of 10,000 sats. Nothing was paid."
• Export CSV saves the calls in a spreadsheet file.
• Pause all agents refuses every agent call until you click Resume agents.

Tool reference

What SpiffyVault offers an agent. You do not need to know these: the agent reads them itself. All amounts are in satoshis of BSV (100,000,000 satoshis = 1 BSV).

Every pay and prepare_payment call carries the agent's own request_id: the same id never pays twice, so a retry is safe. Payments run one at a time. A link with an amount is paid exactly that amount.

Things to ask

• "What is my SpiffyVault balance, and how much can you still spend today?"
• "What did I pay Maya last month?"
• "Ask Ben for 25,000 sats for the design work, valid for two days, and tell me when it is paid."
• "Pay this SpiffyVault link: …"
• "Prepare a payment of 5,000 sats to Maya for lunch."

Stay safe

• Put in the Agent wallet only what you are ready for an agent to spend.
• Start an agent at Prepare. Give it Pay when you trust what it does.
• Keep The first payment to anyone on: a new payee always comes to you.
• Delete SpiffyVault.mcpb after Claude Desktop has installed it.
• Click Revoke on an agent you no longer use. Its key stops working at once.
• If something looks wrong, click Pause all agents, then read Agents › Activity.

Troubleshooting

"SpiffyVault is not running, or its agent access is off."

Open SpiffyVault and turn on Settings › Agent access (MCP). The agent can reach the wallet only while the app is open.

"SpiffyVault refused the access key."

The key was revoked, or copied wrong. Add the agent again, or click Connect… on its row and copy the key again.

"Port 47321 is in use by another program."

Close the other program, then turn agent access off and on.

Every call is refused

• "The owner has paused agent access.": click Resume agents.
• "The owner has not chosen a wallet for agents." or "The chosen wallet is not an Agent wallet.": choose an Agent wallet under Agents may use.

The agent says it may not pay

The agent has Read or Prepare access. Give it Pay on its row, or let it prepare drafts for you.

A payment was refused

Open the entry under Agents › Activity: its rule check says which limit refused it. Click Change limits… if the limit is too tight.

More

Back to Using SpiffyVault, or see Support.