SDK Setup

​

Installation

npm install @payo/mcp

pnpm add @payo/mcp

yarn add @payo/mcp

​

Requirements

• Node.js 18+
• @modelcontextprotocol/sdk (peer dependency)
• A Payo provider API key

​

Basic Setup

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

// 1. Create your MCP server
const server = new McpServer({
  name: 'my-api',
  version: '1.0.0'
});

// 2. Wrap with payments
const paidServer = withPayments(server, {
  apiKey: process.env.PAYO_API_KEY!,
  pricing: {
    'tool_a': 0.01,
    'tool_b': 0.05,
  }
});

// 3. Register tools (same as before)
paidServer.tool('tool_a', { /* schema */ }, async (args) => {
  // Implementation
});

// 4. Connect transport
paidServer.connect(transport);

​

How It Works

1. Intercepts tool registration - Wraps your tool handlers
2. Checks pricing on each call - Looks up the tool’s price
3. Charges before execution - Calls Payo API for paid tools
4. Executes your handler - Only after successful charge

​

Environment Variables

# Development
export PAYO_API_KEY=sk_live_your_key_here

# Or in .env file
PAYO_API_KEY=sk_live_your_key_here

​

Production Deployment

​

Vercel

{
  "env": {
    "PAYO_API_KEY": "@payo-api-key"
  }
}

vercel secrets add payo-api-key sk_live_xxx

​

Railway

​

Docker

ENV PAYO_API_KEY=""

docker run -e PAYO_API_KEY=sk_live_xxx my-mcp-server

​

TypeScript Support

import {
  withPayments,
  PaymentConfig,
  PricingConfig,
  PaymentError,
  PaymentErrorCode
} from '@payo/mcp';

const config: PaymentConfig = {
  apiKey: process.env.PAYO_API_KEY!,
  pricing: {
    'my_tool': 0.01
  }
};

​

Verifying Setup

1. Start your server locally
   PAYO_API_KEY=sk_live_xxx node server.js
   
2. Call a tool without a token You should see a TOKEN_MISSING error (expected behavior)
3. Call with a valid agent token Set AGENT_TOKEN in your test client. The tool should execute and you should see a charge in your dashboard.

​

Troubleshooting

npm install @payo/mcp

​

Next Steps