Docs › MCP Server

droppay-mcp

MCP server that lets AI agents pay DropPay checkouts automatically. Install it once - agents in Claude Code, Cursor, Windsurf, or any MCP client can then pay any DropPay payment request without you writing any agent-side code.

v0.1.1 on npm. npx droppay-mcp always pulls the latest published version. No global install required.

How it works

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

  1. 1
    Fetches payment details Calls GET/payments/public/{request_id} to get the merchant wallet, destination tag, and exact XRP amount to send.
  2. 2
    Signs and submits the transaction locally Signs an XRP payment transaction using the wallet seed from XRPL_WALLET_SEED. Signing happens on the agent's machine. DropPay never receives the seed or private key.
  3. 3
    Verifies with DropPay Calls POST/payments/{request_id}/verify with the on-chain transaction hash. DropPay confirms the transaction and fires the merchant webhook.

The merchant's 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

Run this command in your terminal. Claude Code will register the MCP server and prompt you for environment variables.

terminal 
claude mcp add droppay -- npx droppay-mcp

Then add your wallet seed to the server's environment config. In Claude Code, edit ~/.claude.json (or run /mcp in a session) and add XRPL_WALLET_SEED to the env block for the droppay server.

Cursor / Windsurf / VS Code

Add droppay-mcp to your MCP client's config file. The exact path varies by client - check your client's documentation for where it stores MCP server configurations.

MCP config (JSON) 
{
  "mcpServers": {
    "droppay": {
      "command": "npx",
      "args": ["droppay-mcp"],
      "env": {
        "XRPL_WALLET_SEED": "sYourWalletSeedHere",
        "MAX_PAYMENT_XRP": "5"
      }
    }
  }
}

Environment variables

Variable Required Description
XRPL_WALLET_SEED required Your XRPL wallet seed, starting with s. The agent signs transactions locally with this seed. It never leaves your machine.
MAX_PAYMENT_XRP optional Maximum XRP allowed per payment. Any payment request above this amount is refused automatically. Default: 1. Set this to the highest amount your agent should ever pay in one transaction.
XRPL_NETWORK optional Set to "testnet" to use the XRPL testnet. Default: mainnet. Testnet XRP has no real-world value - use it for development only.
DROPPAY_BASE_URL optional Override the DropPay API base URL. Leave unset for production use (https://droppayxrp.com).

Tools

get_wallet_info

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

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

pay_droppay_invoice

Pays a DropPay payment request end-to-end. Takes a request_id (found in the pay page URL or the API response) and handles the full flow: fetch details, sign and submit XRP on-chain, verify with DropPay.

Parameter Type Description
request_id required string The 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": "ABCDEF1234567890ABCDEF1234567890...",
  "request_id": "dp_xxxxxxxxxx",
  "amount_xrp": "2.5",
  "merchant": "Acme Corp",
  "description": "API access - 1000 calls",
  "xrpl_explorer": "https://livenet.xrpl.org/transactions/ABCDEF..."
}
Payments above MAX_PAYMENT_XRP are refused automatically. If the payment amount exceeds your configured limit, the tool returns an error before submitting any transaction. Adjust MAX_PAYMENT_XRP in your env config if you need to pay larger amounts.

Security notes

Related