Skip to content

droppay-mcp

MCP server that lets AI agents pay DropPay checkouts automatically. Once installed, any agent in Claude Code, Cursor, Windsurf, or any MCP-compatible client can pay a DropPay payment request without you writing any agent-side payment code.

Published on npm

npx droppay-mcp always pulls the latest version. No global install required.

How it works

droppay-mcp implements the DropPay checkout flow for agents. When an agent calls pay_droppay_invoice with a request_id, the server:

  1. Fetches payment details - calls GET /payments/public/{request_id} for wallet, destination tag, and exact XRP amount
  2. Signs and submits locally - signs the XRPL transaction using XRPL_WALLET_SEED on the agent's machine. DropPay never receives the seed.
  3. Verifies with DropPay - calls POST /payments/{request_id}/verify with the tx hash. DropPay confirms on-chain and fires the merchant webhook.

Your merchant integration does not change. The same payment.confirmed webhook fires whether a customer paid on the pay page or an agent paid via MCP.

Installation

Claude Code

claude mcp add droppay -- npx droppay-mcp

Then add XRPL_WALLET_SEED to the server's env config. Run /mcp in a session or edit ~/.claude.json and add it to the env block under the droppay server entry.

Cursor / Windsurf / VS Code

Add to your MCP client's config file (exact path varies by client - check your client's documentation):

{
  "mcpServers": {
    "droppay": {
      "command": "npx",
      "args": ["droppay-mcp"],
      "env": {
        "XRPL_WALLET_SEED": "sYourWalletSeedHere",
        "MAX_PAYMENT_XRP": "5"
      }
    }
  }
}

Environment variables

Variable Required Description
XRPL_WALLET_SEED Yes Your XRPL wallet seed, starting with s. Signing happens locally - never sent to DropPay.
MAX_PAYMENT_XRP No Maximum XRP per payment. Any request above this is refused before submission. Default: 1.
XRPL_NETWORK No Set to "testnet" for development. Default: mainnet.
DROPPAY_BASE_URL No Override the DropPay base URL. Leave unset for production.

Tools

get_wallet_info

Returns the connected wallet address and current XRP balance. Call this before paying to confirm the wallet is configured and funded.

{
  "address": "rYourXRPLWalletAddress",
  "balance_xrp": "12.450000",
  "network": "mainnet"
}

pay_droppay_invoice

Pays a DropPay payment request end-to-end. Pass a request_id - the server fetches details, submits the XRP transaction, and verifies with DropPay.

Parameter Type Description
request_id string DropPay payment request ID. Found in the pay page URL (/pay/{request_id}) or the request_id field from POST /payments/requests.

Success response:

{
  "success": true,
  "tx_hash": "ABCDEF1234567890...",
  "request_id": "dp_xxxxxxxxxx",
  "amount_xrp": "2.5",
  "merchant": "Acme Corp",
  "description": "API access - 1000 calls",
  "xrpl_explorer": "https://livenet.xrpl.org/transactions/ABCDEF..."
}

Spending cap

Payments above MAX_PAYMENT_XRP are refused before any transaction is submitted. Adjust the env variable if you need to raise the cap.

Security

  • Use a dedicated low-balance wallet. Do not use your primary XRPL wallet for agent payments. Keep only what the agent needs and top it up manually.
  • Do not share your MCP config file. The wallet seed is stored in plain text. Anyone with access to the config can drain the wallet.
  • Set MAX_PAYMENT_XRP as low as practical. Agents can be manipulated via prompt injection. A low cap limits potential damage.
  • DropPay is non-custodial. XRP moves directly from your wallet to the merchant's wallet on the XRP Ledger. DropPay only sees the transaction hash after it confirms.