Skip to main content

​
Installation

Install the Payo SDK in your MCP server project: 
npm install @payo/mcp

​
Requirements

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

​
Basic Setup

Import withPayments and wrap your MCP server:
server.ts
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

withPayments() returns your server with payment logic injected:
  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
Your tool code doesn’t change at all.

​
Environment Variables

Set your API key as an environment variable: 
# Development
export PAYO_API_KEY=sk_live_your_key_here

# Or in .env file
PAYO_API_KEY=sk_live_your_key_here
Never commit your API key to version control. Use environment variables or secrets management.

​
Production Deployment

​
Vercel

vercel.json
{
  "env": {
    "PAYO_API_KEY": "@payo-api-key"
  }
}
Add the secret via Vercel dashboard or CLI: 
vercel secrets add payo-api-key sk_live_xxx

​
Railway

Add environment variable in your Railway dashboard under Variables.

​
Docker

Dockerfile
ENV PAYO_API_KEY=""
Pass at runtime: 
docker run -e PAYO_API_KEY=sk_live_xxx my-mcp-server

​
TypeScript Support

The SDK is fully typed. Import types if needed: 
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

Test your integration:
  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

Ensure you’ve installed the package:
npm install @payo/mcp
The SDK requires an API key. Check:
  • PAYO_API_KEY environment variable is set
  • You’re reading it correctly: process.env.PAYO_API_KEY
  • Verify the API key is a provider key (not agent)
  • Check you’re calling paid tools (not free ones)
  • Ensure the agent token is valid

​
Next Steps

Setting Prices

How to set and update prices

Configuration

All SDK options