
Agent proposes, human signs: a budget guard between AI agents and send21's MCP server. Crypto pay
Agent proposes, human signs: a budget guard between AI agents and send21's MCP server. Crypto pay links and API for people and AI agents.
·
Give an AI agent a spending budget, not your keys. The agent proposes, a human signs. Built on send21, crypto pay links and API for people and AI agents.
A real npm run demo run in mock mode. No keys, no money.
draft.confirmed webhooks; pending proposals reserve budgetnpm install && npm run demo. Add -- --interactive to play the human yourself, or -- --llm with AGENT_LLM_BASE_URL + AGENT_LLM_MODEL (any OpenAI-compatible endpoint, such as a local model server) to replace the scripted agent.cp budget.example.json budget.json: unit (USDC, or a fiat like EUR), cap, period (day / week / month, UTC), per-payment max, coins and named recipients with their addresses.
propose_receiving_address with direction: "Sending"), then sign in and approve each with a passkey or authenticator code. Older accounts can opt in under Settings.drafts:write and drafts:read (add webhooks:manage for step 4). cp .env.example .env, fill in the key and two different tokens: GUARD_TOKEN (for the agent) and ADMIN_TOKEN (for you), each from openssl rand -hex 24.WEBHOOK_PORT behind your own HTTPS address (for example a reverse proxy with a free Let's Encrypt certificate), set PUBLIC_URL, run npm run webhook:register and paste the printed SEND21_WEBHOOK_SECRET into .env.npm run build && npm start, then add the MCP config below to your client.Without SEND21_API_KEY, npm start also runs in mock mode: sign a proposal with curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" http://127.0.0.1:8787/admin/mock/<proposal id>/sign.
Put budget-guard where you would put send21's MCP server. The agent's config holds only GUARD_TOKEN; the send21 key stays inside budget-guard.
Cursor (.cursor/mcp.json) and other clients that speak Streamable HTTP:
{
"mcpServers": {
"send21-budget": {
"url": "http://127.0.0.1:8787/mcp",
"headers": { "Authorization": "Bearer <GUARD_TOKEN>" }
}
}
}Claude Desktop and other clients that launch a command (a stdio bridge to the running guard):
{
"mcpServers": {
"send21-budget": {
"command": "node",
"args": ["/absolute/path/to/send21-agent-budget/dist/src/stdio.js"],
"env": { "GUARD_URL": "http://127.0.0.1:8787/mcp", "GUARD_TOKEN": "<GUARD_TOKEN>" }
}
}
}Both are in client-config/. Compare send21's own config for the direct connection: MCP docs.
| The agent gets | From |
|---|---|
propose_payment { to, amount, coin?, reason, purchaseId? } | budget-guard: checks, reserves, then calls send21 create_draft |
budget_status | budget-guard: spent, reserved, left, reset time, recipients |
get_draft_status, get_draft, get_transaction_template, list_draft_quotes | send21, read-only, only for drafts this guard created |
get_rate, get_fee_schedule | send21, read-only |
resources send21://docs/overview, send21://docs/currencies, send21://fees/schedule, send21://docs/webhooks, send21://brand/* | send21, public |
prompt check_payment | send21 |
Not offered to the agent: create_draft, create_payment_request, submit_lightning_proof, list_address_book, get_payment_request, propose_receiving_address, get_account_status, create_account, and the prompts create_pay_link and handle_amount_mismatch. Proposing is the only way to ask for money.
sequenceDiagram
participant A as AI agent
participant G as budget-guard
participant S as send21 MCP
participant H as Human + own wallet
A->>G: propose_payment { to: "domains", amount: "9", reason }
Note over G: allowed recipient? allowed coin?<br/>≤ per-payment max?<br/>spent + reserved + 9 ≤ cap?<br/>check and reserve in one transaction
alt blocked
G-->>A: ⛔ over_budget + reason (nothing reaches send21)
else allowed
G->>S: create_draft (receiver, network, currency,<br/>amount, memo, idempotencyKey)
S-->>G: draft (core, coreSha256)
Note over G: draft core = what was proposed?<br/>coreSha256 holds?
G-->>A: 📝 proposed, waiting for a human
H->>S: reviews the draft, signs in own wallet
S->>G: POST /webhooks/send21 draft.confirmed (signed V2)
Note over G: verify HMAC + 300 s window, dedupe,<br/>draftId, amount and asset match<br/>→ reserved becomes spent
endA draft is the send21 object for "pay someone else": the human is the sender and signs it in their own wallet. Every proposal reserves its amount until the draft is confirmed (spent), expires, is cancelled or is declined by you (POST /admin/proposals/<id>/decline). A purchase is one purchaseId: a retry returns the same draft and never reserves twice; the send21 idempotencyKey is derived from it.
| Webhook | Proposal | Budget |
|---|---|---|
| (created) | 📝 proposed | reserved |
draft.seen | 👀 seen | reserved |
draft.confirmed, matches | ✅ confirmed | spent (what really arrived, if an accepted amount differed) |
draft.confirmed, does not match | 🚩 flagged | reserved until you look |
draft.amount_mismatch / draft.mismatch_accepted | ⚠️ review | reserved |
draft.mismatch_rejected / draft.mismatch_unresolved | 🚩 flagged (money moved, refunds are manual) | reserved |
draft.expired, draft.cancelled | ⌛ / ✖️ | released |
Lightning is not in the coin list: send21's MCP create_draft has no paymentMethod argument, and Lightning drafts need paymentMethod: "Lightning".
Agents onboard themselves; humans approve where the money lands. Since send21 MCP 1.5.0, new accounts only let a key use addresses the owner approved. Set up the account behind budget-guard with send21's own MCP server (docs):
get_account_status: what still stands between the agent and a live pay link (owner confirmed, receiving-address policy, approved and waiting addresses, fees, next steps).propose_receiving_address: the agent proposes an address (direction: "Receiving" for the owner's own pay-link address, "Sending" for a recipient paid with drafts, like the ones in budget.json). It is saved unapproved.create_payment_request (or here, propose_payment → create_draft) with approved addresses only. Any other address gets 422 address_not_approved and nothing is created.No key yet? The agent can call create_account (POST /api/v1/accounts/agent-signup) with the owner's email and gets a limited bootstrap key. Until the owner takes the account over from the emailed link, creating anything returns 403 owner_not_confirmed. The agent never approves addresses, spends or signs: a human signs every payment in their own wallet.
address_not_approved (422): the recipient's address isn't approved in your send21 account, so no draft was created and the budget is released. Sign in to send21, approve it (passkey or authenticator code), then propose again.owner_not_confirmed (403): the account was created by an agent and the owner hasn't taken it over yet. Open the link send21 emailed you (valid 72 hours) and set up a passkey or password.create_draft call, so parallel proposals cannot both pass. Tested with 50 at once. One process per data file; for several, use a database with row locks.coreSha256 (RFC 8785) must hold, or it is 🚩 and the agent is told not to have it signed.X-Send21-Signature-V2: HMAC-SHA256 over <t>.<delivery id>.<raw body>, constant-time compare, refused when more than 300 s old or in the future. A bad signature gets 401 and nothing is stored.X-Send21-Delivery id, and the receiver ignores deliveries it already handled: a delivery id, or the same event body under a new id, is applied once, written together with the budget change before the 2xx. A failed write answers 500 so send21 retries. Separately, the idempotencyKey returns the same draft.draft.confirmed for a draft this guard created, with the proposed coin, network and exact amount (base units, or fiat cents for a fiat budget), a txId and status: Confirmed, counts as spent. Other integrations' drafts on the same account are ignored.127.0.0.1 with a bearer token; the admin API needs a second, different token; only the webhook port should be public. Data is one JSON file (DATA_FILE, mode 600).npm run check # typecheck + lint + tests (budget, concurrency, idempotency, signature, dedupe, matching, MCP, LLM hook)
FORCE_COLOR=1 DEMO_FAST=1 DEMO_WIDTH=108 npm run demo > /tmp/demo.ansi && npm run render:terminal -- /tmp/demo.ansi docs/terminal.htmlThe mock uses a snapshot of the live tools/list, resources/list and prompts/list (src/mock/send21-mcp-snapshot.json). API reference: send21.io/docs · MCP · webhooks · llms-full.txt. More examples: send21-examples.
Questions: [email protected]. License: MIT.
Pick your client and paste the snippet. Each one is the same server, written the way that client expects it.
claude mcp add send21-budget --transport http http://127.0.0.1:8787/mcp{
"mcpServers": {
"send21-budget": {
"url": "http://127.0.0.1:8787/mcp",
"headers": {
"Authorization": ""
}
}
}
}code --add-mcp '{"name":"send21-budget","url":"http://127.0.0.1:8787/mcp","headers":{"Authorization":""}}'Runs as a hosted service. Your client connects over the network and nothing is installed locally.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/send21-agent-budget to learn what the "send21 agent budget" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
This server doesn't publish a machine-readable tool manifest, and it doesn't expose a public endpoint we could ask. Connect the server locally to see what it exposes.
We could not run this server: it ships no npx package for our sandbox and no public endpoint. The four checks that need a live server are left out, and the grade tops out at B until one exists.
Maintain this server? Claiming proves you own the listing and earns the last 4 points.
Claim this listingPaste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/send21-agent-budget)Nothing comparable is listed yet.
No tagged releases on record.
Connect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "send21-agent-budget" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.