Skip to main content
Glama

perly-pay-mcp

Sell your work for crypto from your AI coding assistant. perly-pay-mcp is a local MCP server for Perly Pay: your assistant can create products, prices, payment links and invoices, pay them in test mode, read payments and receipts, and check a buyer's access. Bitcoin, USDC and USDT land straight in your own wallet; Perly Pay never holds them. It costs 2.5¢ a payment, never more than 0.5% of it, and a month of up to 21 payments is free.

It runs on your machine over stdio and talks only to Perly Pay's public API with your key. There is no server of ours in between.

Set up

Get a test key in Perly Pay: Dashboard → Developers → API keys (sk_test_…).

Claude Code

claude mcp add perly-pay --env PERLY_PAY_SECRET_KEY=sk_test_… -- npx -y perly-pay-mcp

Cursor: ~/.cursor/mcp.json, or .cursor/mcp.json in a project

{
  "mcpServers": {
    "perly-pay": {
      "command": "npx",
      "args": ["-y", "perly-pay-mcp"],
      "env": { "PERLY_PAY_SECRET_KEY": "sk_test_…" }
    }
  }
}

Codex: ~/.codex/config.toml

[mcp_servers.perly-pay]
command = "npx"
args = ["-y", "perly-pay-mcp"]
env = { PERLY_PAY_SECRET_KEY = "sk_test_…" }

Keep the key out of git: a config file in a project is often committed. Node 20 or newer.

Variable

PERLY_PAY_SECRET_KEY

sk_test_… while you build. sk_live_… reads only (see below).

PERLY_PAY_API

Default https://pay.perly.io. A perly.io host or this machine; plain http only for localhost.

PERLY_PAY_ALLOW_ANY_API

1 sends your key to any other https host in PERLY_PAY_API, for a copy you run yourself.

PERLY_PAY_WEBHOOK_SECRET

Optional whsec_…, the default for verify_webhook_signature.

Related MCP server: Yolfi MCP server

Try it

Sell a one-hour consultation for $49 with a payment link, then pay it in test mode and show me the payment.

The assistant calls create_product, create_price, create_payment_link, simulate_payment and list_payments.

Tools

Area

Tools

Products and prices

create_product, list_products, update_product, create_price, list_prices, update_price

Payment links

create_payment_link, list_payment_links, update_payment_link

Invoices and checkout

create_invoice, list_invoices, retrieve_invoice, cancel_invoice, create_checkout_session, retrieve_checkout_session

Customers

create_customer, list_customers, retrieve_customer

Subscriptions (renewed by invoice)

create_subscription, list_subscriptions, retrieve_subscription

Access and credits

check_entitlement, list_entitlements, consume_entitlement_credits, list_credit_usage

Money in, read only

list_payments, retrieve_payment, list_receipts, retrieve_receipt, list_events

Refunds

create_refund, list_refunds

Webhooks

create_webhook_endpoint, list_webhook_endpoints, delete_webhook_endpoint

Test mode

simulate_payment: pays an invoice, or buys from a payment link and pays that

On your machine

verify_webhook_signature checks a Perly-Signature; pay_links gives the dashboard pages only you can use: plan, wallet, go live, two-factor, keys

The tools are generated from Perly Pay's OpenAPI document, so their arguments are the API's own.

What it will not do

  • With a live key, it only reads. Every tool that writes is refused: creating invoices, checkout sessions, products, prices, customers, payment links and subscriptions, cancelling, editing, refunds, credit spending, simulated payments and webhook endpoints. It says why, and you do it in the dashboard or in your app's own code. Lists and lookups work as in test. Why: text a buyer typed can reach the assistant, and nothing the server receives proves that you, not the model, approved a live change (confirm: true is written by the model; a client's approval prompt and an MCP elicitation answer both come back through the client). So the server never writes with a live key.

  • Wallets, API keys, billing, live mode and two-factor have no tool at all. You set them in the dashboard; pay_links gives the pages.

  • What cannot be undone (cancelling an invoice, opening a refund, deleting a webhook endpoint) waits for confirm: true, which the assistant should only send after asking you.

  • Your secret key is never repeated in an answer or a log.

  • Buyers' license keys never reach the assistant: an event that carries one comes back without its key; they stay in the dashboard.

  • Text others wrote is marked as data. Customer names, emails, descriptions and metadata can come from buyers, or from anyone who opens a payment link; every API answer ends with a note telling the assistant not to follow them. Still read what a tool is about to change before you approve it.

Docs: https://pay.perly.io/docs/mcp. API reference: https://pay.perly.io/docs/api. MIT licence.

Available Tools

38 tools
cancel_invoiceCancel an invoiceA
Destructive

Cancel an invoice.

Only while nothing has arrived. Money that arrives later is still seen (the address stays watched) and lands in review.

Test keys only: refused with a live key.

Cannot be undone — Cancels the invoice: its buyer can no longer pay it. Ask the person first, then call with confirm: true.

Inputs: id (required), confirm (required).

check_entitlementCheck accessB
Read-onlyIdempotent

Check access.

One call: may this customer use this product now? Name the customer by customer, customer_email or customer_external_id, and the product by product (or price).

Inputs: price, product, customer, customer_email, +1 more.

consume_entitlement_creditsSpend creditsA

Spend credits.

Spends credits from one credit pack, atomically. Refused when fewer are left. action labels the spend for your reports; with an Idempotency-Key a retry never spends twice. To spend from a customer's packs together, use POST /credits/consume.

Test keys only: refused with a live key.

Inputs: id (required), credits (required), action.

create_checkout_sessionCreate a checkout sessionA

Create a checkout session.

A cart of 1–20 prices in one currency. Send the buyer to url, or open it in an overlay with pay.js (data-session="cs_…"). The buyer comes back to return_url after paying, cancel_url if they leave. Live mode: a new session is refused with 403 bill_overdue while a Perly Pay bill is unpaid past its 14 days.

Test keys only: refused with a live key.

Inputs: line_items (required), coupon, customer, metadata, +4 more.

create_customerCreate a customerC

Create a customer.

Test keys only: refused with a live key.

Inputs: name, email, locale, country, +2 more.

create_invoiceCreate an invoiceA

Create an invoice.

Lines are prices ({ price, quantity }) or your own ({ description, amount, quantity }), in one currency. For a single amount, amount + description is short for one line. customer is an id or { email }. A price line may carry its own description ("Seat #12"), and discount takes an amount off this invoice alone. The buyer pays at url, choosing bitcoin or a stablecoin there. Live mode: a new invoice is refused with 403 bill_overdue while a Perly Pay bill is unpaid past its 14 days, until it is paid in the dashboard's Billing; invoices already made are still paid.

Test keys only: refused with a live key.

Inputs: amount, coupon, locale, currency, +9 more.

create_priceCreate a priceA

Create a price.

Every model: one_time, pay_what_you_want (with a minimum), fixed_term (N days of access), subscription (interval, trial, grace, prepay), lifetime (optional cap and cohort tiers), credit_pack. Amounts are immutable; make a new price to change one.

Body is one of: model = one_time: needs product, model, unit_amount; model = pay_what_you_want: needs product, model, custom_amount; model = fixed_term: needs product, model, unit_amount, term_days; model = subscription: needs product, model, unit_amount, recurring; model = lifetime: needs product, model; model = credit_pack: needs product, model, unit_amount, credits.

Test keys only: refused with a live key.

Inputs: model (required), product (required), credits, refunds, +8 more.

create_productCreate a productB

Create a product.

Test keys only: refused with a live key.

Inputs: name (required), active, metadata, image_url, +3 more.

create_refundOpen a refundA
Destructive

Open a refund.

Starts a refund in the asset that was paid. We email the buyer a link to give an address; the link is never returned, since whoever holds it decides where the money goes. With no email on the invoice, the owner makes one in the dashboard. When the address is checked, the refund is ready_to_send with amount_to_send. Refused with sanctioned_sender when money on the invoice came from an address on a sanctions list, or one the coin's issuer froze: sending it back may itself be prohibited, so nothing refunds it — leave it and talk to a lawyer.

Test keys only: refused with a live key.

Cannot be undone — Opens a refund to the buyer. Ask the person first, then call with confirm: true.

Inputs: confirm (required), invoice (required), amount, reason.

create_subscriptionCreate a subscriptionB

Create a subscription.

Renewed by invoice: the customer pays each period themselves. Without a trial the first invoice opens now (latest_invoice); the subscription turns active when it is paid.

Test keys only: refused with a live key.

Inputs: price (required), customer (required), coupon, metadata, +2 more.

create_webhook_endpointCreate a webhook endpointA

Create a webhook endpoint.

The response carries secret — the only time you see it. Keep it to verify Perly-Signature.

Test keys only: refused with a live key.

Inputs: url (required), description, enabled_events.

delete_webhook_endpointDelete a webhook endpointA
Destructive

Delete a webhook endpoint.

Test keys only: refused with a live key.

Cannot be undone — Deletes the webhook endpoint: its events stop. Ask the person first, then call with confirm: true.

Inputs: id (required), confirm (required).

list_credit_usageList credit spendsA
Read-onlyIdempotent

List credit spends.

Newest first; pass next_cursor back as cursor for the next page.

Inputs: limit, action, cursor, product, +1 more.

list_customersList customersC
Read-onlyIdempotent

List customers.

Newest first; pass next_cursor back as cursor for the next page.

Inputs: email, limit, cursor, external_id.

list_entitlementsList entitlementsC
Read-onlyIdempotent

List entitlements.

Newest first; pass next_cursor back as cursor for the next page.

Inputs: limit, cursor, product, customer, +1 more.

list_eventsList eventsA
Read-onlyIdempotent

List events.

What happened in the last 30 days, newest first. type filters (invoice.paid, or invoice.*).

Newest first; pass next_cursor back as cursor for the next page.

Inputs: type, limit, cursor, object.

list_invoicesList invoicesC
Read-onlyIdempotent

List invoices.

Newest first; pass next_cursor back as cursor for the next page.

Inputs: limit, cursor, status, customer, +1 more.

list_paymentsList paymentsA
Read-onlyIdempotent

List payments.

Transfers seen on chain into addresses we handed out, newest first.

Newest first; pass next_cursor back as cursor for the next page.

Inputs: asset, limit, cursor, invoice.

list_pricesList pricesC
Read-onlyIdempotent

List prices.

Newest first; pass next_cursor back as cursor for the next page.

Inputs: limit, model, active, cursor, +1 more.

list_productsList productsB
Read-onlyIdempotent

List products.

Newest first; pass next_cursor back as cursor for the next page.

Inputs: limit, active, cursor.

list_receiptsList receiptsB
Read-onlyIdempotent

List receipts.

One for every fulfilled payment and every confirmed refund, newest first.

Newest first; pass next_cursor back as cursor for the next page.

Inputs: kind, limit, cursor, invoice.

list_refundsList refundsB
Read-onlyIdempotent

List refunds.

Newest first; pass next_cursor back as cursor for the next page.

Inputs: limit, cursor, status, invoice.

list_subscriptionsList subscriptionsB
Read-onlyIdempotent

List subscriptions.

Newest first; pass next_cursor back as cursor for the next page.

Inputs: limit, price, cursor, status, +1 more.

list_webhook_endpointsList webhook endpointsA
Read-onlyIdempotent

List webhook endpoints.

Newest first; pass next_cursor back as cursor for the next page.

Inputs: limit, cursor.

retrieve_checkout_sessionRetrieve a checkout sessionC
Read-onlyIdempotent

Retrieve a checkout session.

Inputs: id (required).

retrieve_customerRetrieve a customerC
Read-onlyIdempotent

Retrieve a customer.

Inputs: id (required).

retrieve_invoiceRetrieve an invoiceC
Read-onlyIdempotent

Retrieve an invoice.

Inputs: id (required).

retrieve_paymentRetrieve a paymentC
Read-onlyIdempotent

Retrieve a payment.

Inputs: id (required).

retrieve_receiptRetrieve a receiptC
Read-onlyIdempotent

Retrieve a receipt.

Inputs: id (required).

retrieve_subscriptionRetrieve a subscriptionC
Read-onlyIdempotent

Retrieve a subscription.

Inputs: id (required).

simulate_paymentSimulate a payment (test mode only)A

Simulate a payment (test mode only).

Test keys only. full pays the amount due: the invoice turns paid and is fulfilled — entitlements, license keys, a receipt, and the events your webhooks get. short sends half (underpaid), over a tenth more (overpaid); those two need the buyer's chain and asset chosen first. For full, an invoice with no chain yet gets one: chain and asset if given, else the first stablecoin offered (refund terms count as accepted).

Pass the invoice's id, or a payment_link id: then a test invoice is made for the link's price (as a buyer opening the link would) and paid.

Test keys only: refused with a live key.

Inputs: id, asset, chain, outcome, +1 more.

update_priceUpdate a priceA
DestructiveIdempotent

Update a price.

Nickname, active, refund terms (refunds replaces them whole; what you leave out takes its default) and metadata. Amounts and the model never change.

Test keys only: refused with a live key.

Inputs: id (required), active, refunds, metadata, +1 more.

update_productUpdate a productA
DestructiveIdempotent

Update a product.

Set active: false to stop selling it; products are never deleted (invoices point at them).

Test keys only: refused with a live key.

Inputs: id (required), name, active, metadata, +4 more.

verify_webhook_signatureVerify a webhook signatureA
Read-onlyIdempotent

Checks a Perly Pay webhook on this machine: the HMAC-SHA256 in its Perly-Signature header against the raw body and the endpoint's signing secret, and that it is under five minutes old. Nothing is sent anywhere. Use it to debug a webhook handler that rejects real events.

Pass the body exactly as received (the raw text, before JSON parsing). secret defaults to PERLY_PAY_WEBHOOK_SECRET.

Inputs: payload (required), signature (required), secret, tolerance_seconds.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 38 tools

    Disambiguation4/5

    Most tools map to a distinct resource and action, and the descriptions clarify differences. However, create_invoice, create_checkout_session, create_payment_link, and create_subscription all represent ways to charge a buyer, so an agent may still need to reason carefully about which flow to use.

    Naming Consistency5/5

    Names consistently use snake_case with a verb-first pattern such as list_invoices, create_product, retrieve_receipt, and delete_webhook_endpoint. The one meta tool, pay_links, is slightly unusual semantically but still fits the snake_case convention.

    Tool Count2/5

    With 38 tools, the surface is well past the 25-tool threshold and feels heavy for an agent to navigate, even for a broad payments platform. Many resources have separate list/create/retrieve/update tools that could potentially be consolidated.

    Completeness3/5

    Core resources generally have create/list/retrieve coverage, and refunds, receipts, events, and webhooks are represented. But there are notable gaps: subscriptions lack update/cancel operations, customers lack update, and several resources such as products, prices, payment links, and refunds lack a retrieve operation.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding agents to add stablecoin checkout, payment links, payment status checks, webhook verification, and webhook-based access logic to applications through crypto payment APIs.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding agents to add stablecoin checkout, payment links, payment status checks, webhook verification, and webhook-based entitlement logic to applications. It also provides tools for workspace registration, settlement and webhook configuration, paylink creation, and crypto payment status checks.
      -