perly-pay-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@perly-pay-mcp Create a $49 payment link for a one-hour consultation and pay it in test mode"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpCursor: ~/.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 | |
|
|
| Default |
|
|
| Optional |
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 |
|
Payment links |
|
Invoices and checkout |
|
Customers |
|
Subscriptions (renewed by invoice) |
|
Access and credits |
|
Money in, read only |
|
Refunds |
|
Webhooks |
|
Test mode |
|
On your machine |
|
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: trueis 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_linksgives 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 toolscancel_invoiceCancel an invoiceADestructive
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 accessBRead-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_payment_linkCreate a payment linkB
Create a payment link.
A page at /l/ that sells one price. Share it anywhere, or open it with pay.js.
Test keys only: refused with a live key.
Inputs: price (required), slug, metadata, quantity, +4 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 refundADestructive
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 endpointADestructive
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 spendsARead-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 customersCRead-onlyIdempotent
List customers.
Newest first; pass next_cursor back as cursor for the next page.
Inputs: email, limit, cursor, external_id.
list_entitlementsList entitlementsCRead-onlyIdempotent
List entitlements.
Newest first; pass next_cursor back as cursor for the next page.
Inputs: limit, cursor, product, customer, +1 more.
list_eventsList eventsARead-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 invoicesCRead-onlyIdempotent
List invoices.
Newest first; pass next_cursor back as cursor for the next page.
Inputs: limit, cursor, status, customer, +1 more.
list_payment_linksList payment linksARead-onlyIdempotent
List payment links.
Newest first; pass next_cursor back as cursor for the next page.
Inputs: limit, price, active, cursor.
list_paymentsList paymentsARead-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 pricesCRead-onlyIdempotent
List prices.
Newest first; pass next_cursor back as cursor for the next page.
Inputs: limit, model, active, cursor, +1 more.
list_productsList productsBRead-onlyIdempotent
List products.
Newest first; pass next_cursor back as cursor for the next page.
Inputs: limit, active, cursor.
list_receiptsList receiptsBRead-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 refundsBRead-onlyIdempotent
List refunds.
Newest first; pass next_cursor back as cursor for the next page.
Inputs: limit, cursor, status, invoice.
list_subscriptionsList subscriptionsBRead-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 endpointsARead-onlyIdempotent
List webhook endpoints.
Newest first; pass next_cursor back as cursor for the next page.
Inputs: limit, cursor.
pay_linksDashboard pages for what a person must doARead-onlyIdempotent
The Perly Pay dashboard pages for steps no API key can take: pay a Perly Pay bill, connect a wallet (public key only), go live, set up two-factor sign-in, manage API keys and live webhooks, send live refunds, and the go-live checklist.
Give the person the link and say what to do there; do not try these through other tools.
Inputs: topic.
retrieve_checkout_sessionRetrieve a checkout sessionCRead-onlyIdempotent
Retrieve a checkout session.
Inputs: id (required).
retrieve_customerRetrieve a customerCRead-onlyIdempotent
Retrieve a customer.
Inputs: id (required).
retrieve_invoiceRetrieve an invoiceCRead-onlyIdempotent
Retrieve an invoice.
Inputs: id (required).
retrieve_paymentRetrieve a paymentCRead-onlyIdempotent
Retrieve a payment.
Inputs: id (required).
retrieve_receiptRetrieve a receiptCRead-onlyIdempotent
Retrieve a receipt.
Inputs: id (required).
retrieve_subscriptionRetrieve a subscriptionCRead-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_payment_linkUpdate a payment linkCDestructiveIdempotent
Update a payment link.
Test keys only: refused with a live key.
Inputs: id (required), active, metadata, quantity, +4 more.
update_priceUpdate a priceADestructiveIdempotent
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 productADestructiveIdempotent
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 signatureARead-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
Scored across 38 tools
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.
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.
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.
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
Related MCP Connectors
Stripe payments for AI agents. Create links, verify, manage customers.
Non-custodial crypto payments for AI assistants: balances, payments, and create payment links.
Let AI agents add Yolfi crypto checkout, paylinks, webhooks, and status checks.
Non-custodial crypto payments: checkout sessions, invoices, webhooks and test payments. No KYC.
Related MCP Servers
- FlicenseNot gradedqualityAmaintenanceEnables 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.-
- FlicenseNot gradedqualityAmaintenanceLets AI coding agents integrate crypto checkout, payment links, payment status checks, and webhook-based entitlements into applications.-
- FlicenseNot gradedqualityAmaintenanceEnables 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.-
- AlicenseNot gradedqualityAmaintenanceEnables AI coding agents to add stablecoin checkout, create payment links and invoices, configure webhooks, verify payment signatures, and gate access based on confirmed payment events.MIT