Skip to main content

Tools

The SolvaPay MCP Server exposes 38 tools across 8 domains. Every tool is scoped to your account — you can only access data belonging to your API key.

Customer Management​

ToolDescription
create_customerCreate a new customer
get_customerRetrieve a customer by reference
list_customersList customers with search and pagination
update_customerUpdate a customer's details
delete_customerDelete a customer
ensure_customerCreate or retrieve a customer by email (idempotent)

create_customer​

ParameterTypeRequiredDescription
emailstringYesCustomer email address
namestringNoCustomer display name
telephonestringNoCustomer telephone number
metadataobjectNoArbitrary key-value metadata

get_customer​

ParameterTypeRequiredDescription
referencestringYesCustomer reference (e.g. cus_A1B2C3D4)

list_customers​

ParameterTypeRequiredDefaultDescription
limitnumberNo20Maximum results to return
offsetnumberNo0Pagination offset
searchstringNo—Search by name or email

update_customer​

ParameterTypeRequiredDescription
referencestringYesCustomer reference
namestringNoUpdated name
emailstringNoUpdated email
telephonestringNoUpdated telephone
metadataobjectNoUpdated metadata

delete_customer​

ParameterTypeRequiredDescription
referencestringYesCustomer reference

ensure_customer​

Creates a customer if one doesn't exist for the given email. Returns the existing customer if found.

ParameterTypeRequiredDescription
emailstringYesCustomer email (used as unique key)
namestringNoCustomer name (used only on creation)
externalRefstringNoYour system's ID for this customer

Agent Management​

ToolDescription
create_agentCreate a new AI agent
get_agentRetrieve an agent by reference
list_agentsList agents with search and filters
update_agentUpdate an agent's details
delete_agentDelete an agent

create_agent​

ParameterTypeRequiredDescription
namestringYesAgent name
descriptionstringNoAgent description
categoriesstring[]NoCategory tags

get_agent​

ParameterTypeRequiredDescription
referencestringYesAgent reference (e.g. agt_P9Q0R1S2)

list_agents​

ParameterTypeRequiredDefaultDescription
limitnumberNo20Maximum results
offsetnumberNo0Pagination offset
searchstringNo—Search by name
statusstringNo—Filter by status

update_agent​

ParameterTypeRequiredDescription
referencestringYesAgent reference
namestringNoUpdated name
descriptionstringNoUpdated description
categoriesstring[]NoUpdated categories

delete_agent​

ParameterTypeRequiredDescription
referencestringYesAgent reference

Plan Management​

ToolDescription
create_planCreate a pricing plan
get_planRetrieve a plan by reference
list_plansList plans with filters
update_planUpdate a plan
delete_planDelete a plan
list_plans_for_agentList plans assigned to a specific agent

create_plan​

ParameterTypeRequiredDefaultDescription
namestringYes—Plan name
typestringYes—Plan type (recurring, one-time, usage-based)
pricenumberYes—Price in smallest currency unit (e.g. cents)
currencystringNoUSDISO 4217 currency code
intervalstringNo—Billing interval (month, year)
descriptionstringNo—Plan description
featuresstring[]No—Feature descriptions
usageLimitnumberNo—Maximum usage units per period

get_plan​

ParameterTypeRequiredDescription
referencestringYesPlan reference (e.g. pln_F1G2H3J4)

list_plans​

ParameterTypeRequiredDefaultDescription
limitnumberNo20Maximum results
offsetnumberNo0Pagination offset
typestringNo—Filter by plan type
statusstringNo—Filter by status

update_plan​

ParameterTypeRequiredDescription
referencestringYesPlan reference
namestringNoUpdated name
pricenumberNoUpdated price
featuresstring[]NoUpdated features
descriptionstringNoUpdated description

delete_plan​

ParameterTypeRequiredDescription
referencestringYesPlan reference

list_plans_for_agent​

ParameterTypeRequiredDescription
agentRefstringYesAgent reference

Purchase Management​

ToolDescription
list_purchasesList all purchases
get_purchaseRetrieve a purchase by ID
get_purchases_by_customerPurchases for a customer
get_purchases_by_agentPurchases for an agent
cancel_renewalCancel renewal of a purchase
check_limitsCheck usage limits for a customer/agent pair

list_purchases​

ParameterTypeRequiredDescription
statusstringNoFilter by status

get_purchase​

ParameterTypeRequiredDescription
idstringYesPurchase ID or reference

get_purchases_by_customer​

ParameterTypeRequiredDescription
customerRefstringYesCustomer reference
statusstringNoFilter by status

get_purchases_by_agent​

ParameterTypeRequiredDescription
agentRefstringYesAgent reference
statusstringNoFilter by status

cancel_renewal​

ParameterTypeRequiredDescription
purchaseRefstringYesPurchase reference
reasonstringNoCancellation reason

check_limits​

Returns usage limit status. If limits are exceeded, includes a checkout URL for the customer to upgrade.

ParameterTypeRequiredDescription
customerRefstringYesCustomer reference
agentRefstringYesAgent reference

Payment & Checkout​

ToolDescription
create_checkout_sessionGenerate a checkout URL
create_customer_sessionGenerate a customer billing portal URL

create_checkout_session​

ParameterTypeRequiredDescription
customerRefstringYesCustomer reference
agentRefstringYesAgent reference
planRefstringNoPlan reference (uses default if omitted)
returnUrlstringNoRedirect URL after checkout

create_customer_session​

Generates a URL where the customer can manage their billing, payment methods, and purchases.

ParameterTypeRequiredDescription
customerRefstringYesCustomer reference

Wallet & Revenue​

ToolDescription
get_wallet_balanceGet your wallet balance
get_agent_balanceGet revenue for a specific agent
get_wallet_statsGet aggregated wallet statistics

get_wallet_balance​

No parameters required. Returns your current wallet balance.

get_agent_balance​

ParameterTypeRequiredDescription
agentRefstringYesAgent reference

get_wallet_stats​

No parameters required. Returns aggregated wallet statistics.

Usage Tracking​

ToolDescription
record_usageRecord a single usage event
record_bulk_usageRecord multiple usage events

record_usage​

ParameterTypeRequiredDescription
customerRefstringYesCustomer reference
agentRefstringYesAgent reference
outcomestringYesOutcome (e.g. success, failure)
actionstringNoAction name
requestIdstringNoCorrelation ID for tracing
actionDurationnumberNoDuration in milliseconds

record_bulk_usage​

ParameterTypeRequiredDescription
eventsarrayYesArray of usage event objects (same fields as record_usage)

Transactions & Refunds​

ToolDescription
list_transactionsList transactions with filters
get_transactionRetrieve a transaction
get_transaction_statsGet transaction statistics
create_refundRefund a transaction

list_transactions​

ParameterTypeRequiredDefaultDescription
limitnumberNo20Maximum results
offsetnumberNo0Pagination offset
statusstringNo—Filter by status
fromDatestringNo—Start date (ISO 8601)
toDatestringNo—End date (ISO 8601)

get_transaction​

ParameterTypeRequiredDescription
transactionIdstringYesTransaction ID

get_transaction_stats​

ParameterTypeRequiredDescription
fromDatestringNoStart date (ISO 8601)
toDatestringNoEnd date (ISO 8601)

create_refund​

ParameterTypeRequiredDescription
sourceTransactionIdstringYesTransaction ID to refund
amountnumberNoPartial refund amount (full refund if omitted)
reasonstringNoRefund reason