Tomopay client SDK for paid MCP tools — auto-pay, budget controls, multi-protocol.
Drop-in wrapper for the MCP SDK Client that transparently handles PAYMENT_REQUIRED challenges. Your agent calls tools as usual; the client negotiates payment behind the scenes.
npm install @tomopay/clientimport { PaidMcpClient } from "@tomopay/client";
const client = new PaidMcpClient(
{ name: "my-agent", version: "1.0.0" },
{
walletPrivateKey: process.env.WALLET_KEY,
budget: {
maxPerCallCents: 1000, // $10 max per tool call
maxDailyCents: 10000, // $100 daily cap
},
}
);
await client.connect(transport);
// Tools that require payment are handled automatically
const result = await client.callTool({
name: "premium-search",
arguments: { query: "market analysis" },
});Set spending limits to prevent runaway costs:
const client = new PaidMcpClient(
{ name: "my-agent", version: "1.0.0" },
{
walletPrivateKey: process.env.WALLET_KEY,
budget: {
maxPerCallCents: 500, // reject any single call over $5
maxDailyCents: 5000, // stop after $50/day
},
}
);Throws BudgetExceededError when a tool's price exceeds either limit.
Require human approval before paying:
const client = new PaidMcpClient(
{ name: "my-agent", version: "1.0.0" },
{
walletPrivateKey: process.env.WALLET_KEY,
onPaymentRequired: async (info) => {
console.log(`Tool "${info.toolName}" costs ${info.amountCents}c (${info.protocol})`);
return confirm("Approve?"); // return false to reject
},
}
);Throws PaymentRejectedError when the callback returns false.
const stats = client.getSpendingStats();
// { totalCents: 1500, todayCents: 500, callCount: 3 }| Protocol | Credential Config Key | Description |
|---|---|---|
x402 |
walletPrivateKey |
HMAC-SHA256 signed challenges |
stripe |
stripePaymentMethodId |
Stripe payment method pass-through |
mpp |
mppSessionToken |
Micropayment protocol session token |
- Your agent calls
client.callTool()as normal. - If the server returns
PAYMENT_REQUIRED, the client parses the challenge. - Budget limits are checked. The
onPaymentRequiredcallback is called (if set). - The appropriate signer produces a proof for the challenge's protocol.
- The tool call is retried with
_payment: { nonce, proof, protocol }in arguments. - The spend is recorded in the budget tracker.
- The successful result is returned to your agent — transparently.
This client is designed to work with @tomopay/gateway, the server-side Tomopay payment gateway for MCP tools.
MIT
- @tomopay/gateway — server-side payment gateway: wrap any MCP server with payment enforcement
- tomopay-demo — full end-to-end demo of the payment loop
- Tutorial: Monetise your MCP tool in 5 minutes