MCP server for AI agents
send21 runs a Model Context Protocol server at https://send21.io/mcp (Streamable HTTP, stateless). An agent can prepare and track payments with a scoped API key, and no key can move funds: a human or the operator's own wallet signs every payment.
Connect
Two ways in: sign in (below, no key to copy) or the same Authorization: Bearer s21_... header as the REST API. Listing the tools, reading the fee schedule, and every resource and prompt work without either; every other tool needs one.
Coding agents such as Cursor, Claude Code and VS Code can add send21 as a remote MCP server and build payments into your app while they write the code. Create a key in API keys with only the scopes the job needs. No key can move funds.
Cursor (.cursor/mcp.json), LM Studio (Program tab, Install, Edit mcp.json) and other clients that use mcpServers:
{
"mcpServers": {
"send21": {
"url": "https://send21.io/mcp",
"headers": { "Authorization": "Bearer s21_YOUR_KEY" }
}
}
}Sign in instead of a key
Clients that support MCP sign-in (OAuth), such as Claude, Claude Code, Cursor, VS Code and Muse Code, can connect without a key. Add https://send21.io/mcp/oauth as a remote MCP server with no headers. The client opens send21 in your browser; you sign in, see what the app asks for, and approve. In Claude, add it as a custom connector with that URL.
The app gets a token that renews itself every hour. It works like an API key with the scopes you approved, but only ever with receiving addresses you approved, whatever your account setting. You get an email for each new connection, and it is listed under API keys as a connected app, where Disconnect ends it at once. A connection nobody uses for 90 days ends by itself.
https://send21.io/mcp takes sign-in too, but only asks for it when a tool needs it, so directories can list the tools without signing in. /mcp/oauth asks on the first request, which is what clients need to offer the sign-in when you add the server. Discovery: /.well-known/oauth-protected-resource/mcp/oauth and /.well-known/oauth-authorization-server (authorization code with PKCE S256, dynamic client registration, rotating refresh tokens).
claude mcp add --transport http send21 https://send21.io/mcp/oauth
# then run /mcp in Claude Code and choose send21 to sign inConnect from Claude Code
With a key:
claude mcp add --transport http send21 https://send21.io/mcp \
--header "Authorization: Bearer s21_YOUR_KEY"Connect from VS Code
In .vscode/mcp.json:
{
"servers": {
"send21": {
"type": "http",
"url": "https://send21.io/mcp",
"headers": { "Authorization": "Bearer s21_YOUR_KEY" }
}
}
}Connect from Muse Code
Meta's coding agent takes send21 in mcp_servers; see Use send21 with Muse Code.
Rules for a coding agent
Paste this into your AGENTS.md, CLAUDE.md or Cursor rules, so the agent keeps to them while it builds:
## Payments (send21)
- Use the send21 MCP server for crypto pay links. Read send21://docs/overview first.
- Create pay links with create_payment_request. Send an orderId with reuseOpenForOrder: true, so a retry returns the open link instead of creating a second one.
- Pay links only go to receiving addresses the owner approved. If you need a new one, call propose_receiving_address and tell me; I approve it myself. A 422 address_not_approved means it is not approved yet.
- Call get_account_status when something is blocked and follow its next steps.
- Never mark an order paid from the browser. Wait for the signed webhook (draft.confirmed), verify X-Send21-Signature-V2, and check amount, asset and orderId on the server. Retries reuse X-Send21-Delivery: ignore deliveries you already handled.
- Amount mismatches are mine to decide; never accept or decline one.
- Never hold keys, sign or send payments. The payer signs in their own wallet.Frameworks
For agents built in code rather than connected over MCP, send21 also comes as framework packages:
- LangChain:
pip install langchain-send21 - Vercel AI SDK:
npm install ai-sdk-tool-send21 ai zod, send21 tools for TypeScript agents - Cursor and Grok Bot plugin: the MCP server plus create-pay-link, check-payment and verify-webhooks skills
- Haystack:
pip install send21-haystack, a component that prepares a pay link (not an official deepset integration)
Tools
| Tool | What it does | Scope |
|---|---|---|
create_payment_request | Create a fiat-priced pay link with the currencies you accept. Optional declineNote (what happens if the human does not pay), shortfallAbsorbUpToPercent and reuseOpenForOrder (one open link per orderId) | drafts:write |
get_payment_request | Read a payment request, its payment status and its changeSignals | drafts:read |
create_draft | Prepare a payment to a receiver address | drafts:write |
get_draft | Read a draft with amounts, fee, quote, core hash and changeSignals | drafts:read |
list_draft_quotes | Every quote (rate lock) of a fiat-priced draft | drafts:read |
get_draft_status | Cheap status snapshot for polling, with reviewState when a payment with a different amount arrived | drafts:read |
get_transaction_template | Wallet-ready payment instructions for a draft | drafts:read |
submit_lightning_proof | Confirm a paid Lightning draft with the payment preimage | drafts:write |
list_address_book | Saved receiver and own addresses, with which ones the owner approved | addressbook:read |
propose_receiving_address | Propose an address for the owner to approve; it stays unusable until they do | addressbook:write |
get_account_status | What stands between the agent and a live pay link, and the next steps | drafts:read |
create_account | Sign the human owner up and get a bootstrap key; the owner takes the account over from an emailed link | none |
get_rate | Exchange rate for an asset in a fiat currency | drafts:read |
get_fee_schedule | The public fee schedule | none |
Resources
Public and read-only, no key needed. They are built from the same sources as this site and the REST API, so they never disagree with them.
| URI | What it holds |
|---|---|
send21://docs/overview | What send21 is and is not, flows, currencies, fees and links (the same text as llms.txt) |
send21://docs/currencies | Every currency and network a payment can use, with the exact API values, and the 161 fiat currencies |
send21://fees/schedule | The fee schedule as JSON, the same as GET /api/v1/fees/schedule |
send21://docs/webhooks | Events, delivery headers, retries and the X-Send21-Signature-V2 check with code |
send21://brand/guidelines | Which logo for which background, colours, spacing, and the download URL of every logo file |
send21://brand/logo-horizontal-on-dark.svg | Main logo for dark backgrounds (also .png, 400 x 114) |
send21://brand/logo-stacked-on-dark.svg | Stacked logo for dark backgrounds and square spaces |
send21://brand/icon-on-dark.svg | The icon alone, for avatars and small spaces |
send21://brand/wordmark-on-light.svg | Wordmark for white or light backgrounds |
send21://brand/wordmark-on-dark.svg | Wordmark for dark backgrounds |
Prompts
Clients such as Claude offer these as ready-made commands. Each one steers the agent through the tools in an order that keeps the rules: your own addresses only, the payer signs in their own wallet, and a person decides about a payment with a different amount.
| Prompt | Arguments | What it does |
|---|---|---|
create_pay_link | amount, fiatCurrency, acceptedCurrencies, optional memo and orderId | Builds the options from your currencies and addresses, calls create_payment_request and returns the link |
check_payment | id (pay link or draft) | Reads the pay link or draft and explains in plain words where it stands |
handle_amount_mismatch | draftId | Shows what was billed and what arrived, and how you accept or decline it; it never decides for you |
Approved addresses: humans approve where the money lands
New accounts only let API keys use addresses the owner approved (receiving-address policy ApprovedOnly; older accounts can turn it on in Settings). A key that names any other address gets 422 address_not_approved and nothing is created, so a prompt-injected agent or a leaked key cannot point a payment at an address of its choosing.
The flow: the agent calls propose_receiving_address. The owner gets an email without any approve link, signs in to send21, compares the address character by character, and approves it with a passkey or an authenticator code. An emailed code is never enough, because an agent that reads the owner's inbox could use it. No API key and no scope can approve an address. get_account_status tells the agent what is still missing.
Pay links need the owner's own approved receiving addresses; drafts may pay any approved address. A pasted Lightning invoice names no address to approve, so with ApprovedOnly a key uses a Lightning address instead. Payments the owner creates in the app are not limited.
Agents sign up, owners take over
An agent without a key can call create_account (or POST /api/v1/accounts/agent-signup) with the owner's email address, its own name and what it will use the account for. It gets a bootstrap key at once (read, drafts and address-book scopes, valid 90 days, shown once), and the owner gets an email with a link to take the account over.
Until the owner opens the link (valid 72 hours) and sets up a passkey or a password, the key can read, propose addresses and call get_account_status, but creating anything returns 403 owner_not_confirmed. After that the approved-address rules apply: the agent creates pay links only to addresses the owner approved. An owner who did not ask for the account deletes it from the same page; an account nobody takes over is deleted after 7 days. At most 3 agent sign-ups per network per day; an email that already has an account gets 409 account_exists, and the agent asks the owner for a key instead.
Agent proposes, human signs
The safe split for agents: the agent creates the payment request or draft, and the payment is signed in a wallet the agent does not control. A compromised agent or API key can create instructions but cannot spend. Every tool calls the REST API in-process, so scopes, validation, idempotency and rate limits are the same as for REST clients.
Tool annotations
Every tool declares a title and the MCP hints. The nine read tools (get_*, list_*) are readOnlyHint: true, so clients that run read-only tools without asking (Muse Code, for example) can check status without a prompt. The five write tools (create_payment_request, create_draft, submit_lightning_proof, propose_receiving_address, create_account) are not read-only. No tool is destructive: none can delete anything or move funds. submit_lightning_proof is idempotent; create_account is openWorldHint: true because it emails the owner.
Payment states
How send21's statuses map to the states agent platforms ask for:
| State | Pay link (`get_payment_request`) | Draft (`get_draft_status`) |
|---|---|---|
| Quoted | Open with draftStatus: AwaitingPayment: the payer picked a currency and the price is locked | AwaitingPayment; a fiat price is locked for 15 minutes |
| Pending | Open with draftStatus: Seen | Seen: the payment is seen, not yet confirmed |
| Confirmed | Completed | Confirmed |
| Failed | Expired unpaid | Expired; a payment with a different amount that was declined or never decided has reviewState rejected or unresolved |
| Cancelled | Cancelled | Cancelled |
No duplicate payments
reuseOpenForOrder: truewith anorderIdreturns the open pay link for that order instead of creating a second one.- An
Idempotency-Key(header, oridempotencyKeyoncreate_draft) makes a retry return the original object; the same key with different parameters is refused. - A payment with a different amount never confirms on its own:
reviewState: pendingwaits for the owner to accept or decline it.
Examples
Open-source example apps, each a working integration you can copy. Every one uses approved addresses and verifies signed webhooks.
- send21-examples: MCP, webhook receiver, LangChain, Vercel AI SDK and Shopify samples
- send21-agent-budget: a budget guard between an AI agent and the MCP server
- send21-over-budget-handoff: an agent with a hard spend cap hands the payment to a human with a pay link, then resumes on the signed webhook
- send21-coffee-button: Lightning-first "buy me a coffee" button, README badge and supporters wall
- send21-file-paywall: sell a file, one pay link per purchase, single-use download links
- send21-telegram-shop: Telegram mini-shop bot with a cart and one pay link per order
- send21-discord-tipbot: Discord tip bot
- send21-stream-tips: tip alerts in your OBS overlay
- send21-split-the-bill: split a bill into one QR per friend
- send21-event-ticket: signed QR tickets with one-time door check-in
- send21-pos-simulator: demo card terminal with a send21 QR option (the card is simulated)
- send21-parking-meter: pay for parking time and extend it from your phone
- send21-pay-per-use: laundromat or arcade machine unlocked by a pay link
Directory listings
- Official MCP Registry:
io.github.send21io/mcp - Smithery: smithery.ai/servers/send21io/mcp
- Glama: glama.ai/mcp/servers/send21io/mcp
- MCP Server Card (connection details before connecting):
https://send21.io/mcp/server-card, listed in the AI Catalog athttps://send21.io/.well-known/ai-catalog.json. The registry entry itself:https://send21.io/mcp/server.json
Related
Start building
Create a free account to get an API key, or try the whole flow first on test networks.
This page is also available as Markdown: /docs/mcp.md. Questions: integration@send21.io.