Skip to main content
The server exposes 12 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.
  1. shop_search finds products. shop_product gets the exact variant.
  2. shop_quote locks a live total and returns a checkout_session_id.
  3. create_payment_session for that exact total returns a payment_url.
  4. The user opens the payment_url and approves with their passkey (a biometric confirmation on their device).
  5. 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. 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.

​
Shopping

​
shop_search — payments:read

Returns product listings: product_id, price estimate, merchant.

​
shop_product — payments:read

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). 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. 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

​
shop_set_default_address — payments:write

​
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.