SDK Overview

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
pnpm
yarn

npm install @payo/mcp

pnpm add @payo/mcp

yarn add @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

Export	Description
`withPayments()`	Wraps an MCP server with payment logic

Types

Export	Description
`PaymentConfig`	Configuration options for `withPayments()`
`PricingConfig`	Tool name → USD price mapping
`PaymentError`	Error class for payment failures
`PaymentErrorCode`	Enum of error codes
`LogLevel`	Logging verbosity levels
`ErrorVerbosity`	`'detailed'` or `'concise'`

Utilities

Export	Description
`PlatformClient`	Direct access to Payo API (advanced)
`SessionManager`	Token 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:

Proxies your server to intercept handler registration
Wraps tool handlers with payment logic
Calls the Payo platform API for charges
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

​Installation

​Requirements

​Quick Example

​Exports

​Main Function

​Types

​Utilities

​TypeScript Support

​Architecture

​Next Steps