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 in

Connect 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

ToolWhat it doesScope
create_payment_requestCreate 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_requestRead a payment request, its payment status and its changeSignalsdrafts:read
create_draftPrepare a payment to a receiver addressdrafts:write
get_draftRead a draft with amounts, fee, quote, core hash and changeSignalsdrafts:read
list_draft_quotesEvery quote (rate lock) of a fiat-priced draftdrafts:read
get_draft_statusCheap status snapshot for polling, with reviewState when a payment with a different amount arriveddrafts:read
get_transaction_templateWallet-ready payment instructions for a draftdrafts:read
submit_lightning_proofConfirm a paid Lightning draft with the payment preimagedrafts:write
list_address_bookSaved receiver and own addresses, with which ones the owner approvedaddressbook:read
propose_receiving_addressPropose an address for the owner to approve; it stays unusable until they doaddressbook:write
get_account_statusWhat stands between the agent and a live pay link, and the next stepsdrafts:read
create_accountSign the human owner up and get a bootstrap key; the owner takes the account over from an emailed linknone
get_rateExchange rate for an asset in a fiat currencydrafts:read
get_fee_scheduleThe public fee schedulenone

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.

URIWhat it holds
send21://docs/overviewWhat send21 is and is not, flows, currencies, fees and links (the same text as llms.txt)
send21://docs/currenciesEvery currency and network a payment can use, with the exact API values, and the 161 fiat currencies
send21://fees/scheduleThe fee schedule as JSON, the same as GET /api/v1/fees/schedule
send21://docs/webhooksEvents, delivery headers, retries and the X-Send21-Signature-V2 check with code
send21://brand/guidelinesWhich logo for which background, colours, spacing, and the download URL of every logo file
send21://brand/logo-horizontal-on-dark.svgMain logo for dark backgrounds (also .png, 400 x 114)
send21://brand/logo-stacked-on-dark.svgStacked logo for dark backgrounds and square spaces
send21://brand/icon-on-dark.svgThe icon alone, for avatars and small spaces
send21://brand/wordmark-on-light.svgWordmark for white or light backgrounds
send21://brand/wordmark-on-dark.svgWordmark 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.

PromptArgumentsWhat it does
create_pay_linkamount, fiatCurrency, acceptedCurrencies, optional memo and orderIdBuilds the options from your currencies and addresses, calls create_payment_request and returns the link
check_paymentid (pay link or draft)Reads the pay link or draft and explains in plain words where it stands
handle_amount_mismatchdraftIdShows 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:

StatePay link (`get_payment_request`)Draft (`get_draft_status`)
QuotedOpen with draftStatus: AwaitingPayment: the payer picked a currency and the price is lockedAwaitingPayment; a fiat price is locked for 15 minutes
PendingOpen with draftStatus: SeenSeen: the payment is seen, not yet confirmed
ConfirmedCompletedConfirmed
FailedExpired unpaidExpired; a payment with a different amount that was declined or never decided has reviewState rejected or unresolved
CancelledCancelledCancelled

No duplicate payments

  • reuseOpenForOrder: true with an orderId returns the open pay link for that order instead of creating a second one.
  • An Idempotency-Key (header, or idempotencyKey on create_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: pending waits 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.

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 at https://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.