Tools Reference

The server exposes 18 tools. Your MCP client discovers them automatically; this page is the map of what they do and how they chain together.

The buy-flow chain

To buy a product, tools must run in this order. The key rule: create_payment_session authorizes payment but never places an order. Only shop_checkout buys.

shop_search finds products. shop_product gets the exact variant.
shop_quote locks a live total and returns a checkout_session_id.
create_payment_session for that exact total returns a payment_url.
The user opens the payment_url and approves with their passkey (a biometric confirmation on their device).
shop_checkout places the order. Credentials stay server-side.

Paying a known total at a named merchant (a bill, an invoice, a checkout the user is already on) skips discovery: create_payment_session → user approves → done.

Payments

create_payment_session — `checkout:run`

Creates a payment session and returns a payment_url for the user to approve. Charges nothing by itself.

Parameter	Type	Notes
`total_amount`	string, required	Decimal string, e.g. `"49.99"`
`currency`	string, required	3-letter ISO 4217, e.g. `USD`
`merchant_name`	string, required	Display name shown to the user
`merchant_url`	string, required	Merchant website URL
`merchant_country`	string, required	2-letter ISO 3166-1, e.g. `US`
`products`	array, required	Line items: `{ description, unit_price, quantity? }`
`idempotency_key`	string, optional	Same key returns the original session instead of a duplicate

Returns { session_id, payment_url, expires_at, replayed }.

get_payment_status — `payments:read`

Checks a payment session. Returns status only: pending, completed, failed, or not_found. Payment credentials never leave the gateway.

Parameter	Type	Notes
`session_id`	string, required	From `create_payment_session`

Mandates

Manage standing mandates — spend authorizations the owner approves once with a passkey, then an agent charges within caps. Setting one up returns an approval URL; it charges nothing by itself. Charging a mandate is not available over MCP — use the CLI or the REST API.

create_mandate — `payments:write`

Starts mandate setup and returns an approval_url for the owner to approve with a passkey. Spends nothing.

Parameter	Type	Notes
`amount`	string, required	Per-charge cap, e.g. `"120.00"`
`currency`	string, required	3-letter ISO 4217, e.g. `USD`
`merchant_name`	string	Required unless `merchant_scope` is `any`
`merchant_url`	string	Required unless `merchant_scope` is `any`
`merchant_country`	string	2-letter ISO 3166-1, e.g. `US`
`recurring_frequency`	string, optional	`one_time` (default), `weekly`, `monthly`, `yearly`
`merchant_scope`	string, optional	`listed` (default) or `any` (one-time only)
`valid_until`	string, optional	ISO 8601; one-time is capped at 7 days
`max_charges`	integer, optional	Maximum number of charges allowed against the mandate
`products`	array, optional	Line items: `{ description, unit_price, quantity? }`

Returns { approval_url, ... }. Send the URL to the owner; after they approve, call list_mandates to confirm the mandate is active before spending against it.

list_mandates — `payments:read`

Returns the owner’s standing mandates (transient per-checkout mandates are excluded). Each entry includes merchant, frequency, approved/remaining amount, status, and validity. No required parameters.

get_mandate — `payments:read`

Returns one mandate with its spend and charge history.

Parameter	Type	Notes
`mandate_id`	string, required	From `list_mandates` (e.g. `mdt_…`)

cancel_mandate — `payments:write`

Revokes a mandate; stops all future charges. Terminal.

Parameter	Type	Notes
`mandate_id`	string, required	From `list_mandates` (e.g. `mdt_…`)

pause_mandate — `payments:write`

Temporarily suspends a mandate. No charges succeed until resumed.

Parameter	Type	Notes
`mandate_id`	string, required	From `list_mandates` (e.g. `mdt_…`)

resume_mandate — `payments:write`

Reactivates a paused mandate.

Parameter	Type	Notes
`mandate_id`	string, required	From `list_mandates` (e.g. `mdt_…`)

Shopping

shop_search — `payments:read`

Parameter	Type	Notes
`query`	string, required	e.g. `"running shoes size 10"`
`merchant`	string, optional	Merchant domain to scope the search
`cursor`	string, optional	Pagination cursor from a prior search

Returns product listings: product_id, price estimate, merchant.

shop_product — `payments:read`

Parameter	Type	Notes
`product_id`	string, required	From `shop_search`
`merchant`	string, optional	Merchant domain from the search result

Returns purchasable offers and variants: variant_id, price, availability.

shop_quote — `payments:write`

Opens a checkout and locks a live price. Requires a delivery address on file (check with shop_list_addresses).

Parameter	Type	Notes
`variant_id`	string, required	From `shop_product`
`merchant`	string, required	Merchant domain from that offer
`quantity`	number, optional	Defaults to 1
`address_id`	string, optional	Defaults to your default address

Returns checkout_session_id plus the exact total to pay.

shop_checkout — `checkout:run`

The required final step. Places the order for a prior quote, paying with an approved payment session. The session’s amount must match the quote total.

Parameter	Type	Notes
`checkout_session_id`	string, required	From `shop_quote`
`payment_session_id`	string, required	An approved session from `create_payment_session`

Returns { status, order_id, amount, replayed }. If the payment isn’t approved yet, the tool says so; poll get_payment_status until completed, then retry.

Addresses

Address reads are masked. Full address details stay server-side and go only to the merchant.

shop_list_addresses — `payments:read`

No parameters. Returns masked summaries (id, label, short summary, which is default) plus whether a contact phone is on file.

shop_add_address — `payments:write`

Parameter	Type	Notes
`first_name`, `last_name`	string, required
`street`	string, required	Line 1; `street2` optional
`city`, `region`, `postal_code`	string, required
`country`	string, required	2-letter ISO 3166-1
`label`	string, optional	e.g. `"Home"`
`phone`	string, optional	Contact phone, saved to the profile
`set_default`	boolean, optional	Make this the default

shop_set_default_address — `payments:write`

Parameter	Type	Notes
`address_id`	string, required	From `shop_list_addresses`

Account

list_cards — `payments:read`

No parameters. Returns the user’s saved cards, masked: last4, brand, expiry. Never full numbers.

list_agents — `payments:read`

No parameters. Returns the user’s connected agents, including this connection.

ping — no scope

Health probe. Returns { pong: true } and the server time. Use it to confirm the connection after setup.

Getting Started

Guides

Prava SDK

Prava MCP

Prava CLI

Resources

The buy-flow chain

Payments

create_payment_session — `checkout:run`

get_payment_status — `payments:read`

Mandates

create_mandate — `payments:write`

list_mandates — `payments:read`

get_mandate — `payments:read`

cancel_mandate — `payments:write`

pause_mandate — `payments:write`

resume_mandate — `payments:write`

Shopping

shop_search — `payments:read`

shop_product — `payments:read`

shop_quote — `payments:write`

shop_checkout — `checkout:run`

Addresses

shop_list_addresses — `payments:read`

shop_add_address — `payments:write`

shop_set_default_address — `payments:write`

Account

list_cards — `payments:read`

list_agents — `payments:read`

ping — no scope

​The buy-flow chain

​Payments

​create_payment_session — checkout:run

​get_payment_status — payments:read

​Mandates

​create_mandate — payments:write

​list_mandates — payments:read

​get_mandate — payments:read

​cancel_mandate — payments:write

​pause_mandate — payments:write

​resume_mandate — payments:write

​Shopping

​shop_search — payments:read

​shop_product — payments:read

​shop_quote — payments:write

​shop_checkout — checkout:run

​Addresses

​shop_list_addresses — payments:read

​shop_add_address — payments:write

​shop_set_default_address — payments:write

​Account

​list_cards — payments:read

​list_agents — payments:read

​ping — no scope

The buy-flow chain

Payments

create_payment_session — `checkout:run`

get_payment_status — `payments:read`

Mandates

create_mandate — `payments:write`

list_mandates — `payments:read`

get_mandate — `payments:read`

cancel_mandate — `payments:write`

pause_mandate — `payments:write`

resume_mandate — `payments:write`

Shopping

shop_search — `payments:read`

shop_product — `payments:read`

shop_quote — `payments:write`

shop_checkout — `checkout:run`

Addresses

shop_list_addresses — `payments:read`

shop_add_address — `payments:write`

shop_set_default_address — `payments:write`

Account

list_cards — `payments:read`

list_agents — `payments:read`

ping — no scope