Prerequisites: An existing MCP server built with the official @modelcontextprotocol/sdk package. Cloudflare MCP package (@cloudflare/agents) support coming soon.Want your MCP framework supported? Contact us at [email protected] 1. Create an Account
Sign in with Google
Authenticate using your Google account.
Select your role
Choose Provider to access the provider dashboard.
2. Create an API Key
On your first visit, you’ll be prompted to create your first API key.
Name your key
Give it a name like “Production Server”.
Copy the key
Copy the key immediately. It starts with sk_live_ and won’t be shown again.
This key authenticates charge requests. Keep it secret and never expose it in client-side code.
3. Install the SDK
4. Wrap Your Server
Import withPayments and wrap your MCP server:
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { withPayments } from '@payo/mcp';
// Create your MCP server as usual
const server = new McpServer({
name: 'weather-api',
version: '1.0.0'
});
// Wrap with payments
const paidServer = withPayments(server, {
apiKey: process.env.PAYO_API_KEY,
pricing: {
'get_weather': 0.01, // $0.01 per call
'get_forecast': 0.05, // $0.05 per call
'get_location': 0, // Free
}
});
// Register tools as normal
paidServer.tool('get_weather', {
description: 'Get current weather for a city',
inputSchema: {
type: 'object',
properties: {
city: { type: 'string' }
},
required: ['city']
}
}, async ({ city }) => {
// Your tool implementation
return { temperature: 72, conditions: 'sunny' };
});
// Start the server
paidServer.connect(transport);
5. Set Environment Variable
Store your API key as an environment variable:
export PAYO_API_KEY=sk_live_your_provider_key_here
6. Deploy
Deploy your server as you normally would. The SDK handles payment automatically:
- Free tools (price: 0) execute immediately
- Paid tools charge the agent first, then execute
- No token? Returns a helpful error message
How Charging Works
When an agent calls get_weather:
- Agent sends a tool call request with their token
- SDK intercepts and sees the price is $0.01
- SDK calls Payo to charge the agent
- Payo validates and transfers $0.01 from agent to provider
- SDK executes your tool handler
- Result returned to agent
Example: Complete Server
Here’s a full example with multiple tools:
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { withPayments } from '@payo/mcp';
const server = new McpServer({
name: 'weather-api',
version: '1.0.0'
});
const paidServer = withPayments(server, {
apiKey: process.env.PAYO_API_KEY!,
pricing: {
'get_weather': 0.01,
'get_forecast': 0.05,
'get_alerts': 0.02,
'list_cities': 0, // Free discovery tool
},
providerName: 'WeatherAPI', // Shown in error messages
errorVerbosity: 'detailed', // Helpful errors for agents
});
// Free tool - no payment required
paidServer.tool('list_cities', {
description: 'List supported cities (free)',
}, async () => {
return ['New York', 'Los Angeles', 'Chicago', 'Houston'];
});
// Paid tools
paidServer.tool('get_weather', {
description: 'Get current weather ($0.01)',
inputSchema: {
type: 'object',
properties: { city: { type: 'string' } },
required: ['city']
}
}, async ({ city }) => {
return { city, temp: 72, conditions: 'sunny' };
});
paidServer.tool('get_forecast', {
description: 'Get 7-day forecast ($0.05)',
inputSchema: {
type: 'object',
properties: { city: { type: 'string' } },
required: ['city']
}
}, async ({ city }) => {
return { city, forecast: ['sunny', 'cloudy', 'rain', 'sunny', 'sunny', 'cloudy', 'sunny'] };
});
// Connect via stdio
const transport = new StdioServerTransport();
paidServer.connect(transport);
Monitoring Earnings
View your earnings in the Wallet page:
- Total earnings
- Transaction history (tool, amount, agent, timestamp)
- Withdrawal options (coming soon)
Next Steps
