Skip to main content
The Payo SDK enables MCP tool providers to charge for tool calls. Wrap your server with withPayments() and the SDK handles authentication, charging, and error handling automatically.

​
Installation

npm install @payo/mcp

​
Requirements

  • Node.js 18+
  • @modelcontextprotocol/sdk - The MCP SDK (peer dependency)
  • Provider API key - From your Payo dashboard

​
Quick Example

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { withPayments } from '@payo/mcp';

const server = new McpServer({ name: 'my-api', version: '1.0.0' });

const paidServer = withPayments(server, {
  apiKey: process.env.PAYO_API_KEY!,
  pricing: {
    'paid_tool': 0.05,
    'free_tool': 0,
  }
});

paidServer.tool('paid_tool', { /* schema */ }, async (args) => {
  // Executes only after successful charge
  return { result: 'data' };
});

​
Exports

The SDK exports the following:

​
Main Function

ExportDescription
withPayments()Wraps an MCP server with payment logic

​
Types

ExportDescription
PaymentConfigConfiguration options for withPayments()
PricingConfigTool name → USD price mapping
PaymentErrorError class for payment failures
PaymentErrorCodeEnum of error codes
LogLevelLogging verbosity levels
ErrorVerbosity'detailed' or 'concise'

​
Utilities

ExportDescription
PlatformClientDirect access to Payo API (advanced)
SessionManagerToken extraction utilities (advanced)

​
TypeScript Support

The SDK is written in TypeScript with full type definitions: 
import type {
  PaymentConfig,
  PricingConfig,
  PaymentError,
  PaymentErrorCode
} from '@payo/mcp';

​
Architecture

The SDK:
  1. Proxies your server to intercept handler registration
  2. Wraps tool handlers with payment logic
  3. Calls the Payo platform API for charges
  4. Executes your handler only after successful payment

​
Next Steps

withPayments()

Full API documentation

Configuration

All configuration options

Error Codes

Error types and handling

Examples

Complete code examples