Architecture Overview
Payo sits between AI agents and MCP tool providers, handling authentication, charging, and settlement.The Charge Flow
When an agent calls a paid tool, here’s what happens:Agent sends tool call
The agent’s MCP client sends a
tools/call request to the provider’s server. The request includes the agent’s token in the Authorization header.SDK checks pricing
The SDK looks up the tool’s price. If price is
0, the tool executes immediately (no charge).SDK charges the agent
For paid tools, the SDK calls the Payo platform with the agent token, tool name, and price.
Platform validates and transfers
Payo validates both keys, checks the agent’s balance, and transfers funds from the agent to the provider.
Atomic Transactions
Every charge is atomic and uses double-entry bookkeeping:- The agent’s credits are debited
- The provider’s earnings are credited
- Both entries are recorded in the ledger
Authentication
Payo uses two types of keys:| Key Type | Format | Used By | Purpose |
|---|---|---|---|
| Agent Token | sk_live_... | Agents | Identifies who’s being charged |
| Provider Key | sk_live_... | Providers | Authenticates charge requests |
Keys are stored securely as hashes. The raw key is shown once at creation and cannot be retrieved again.
Transport Support
The SDK extracts agent tokens from:- HTTP Transport
- stdio Transport
Error Handling
When a charge fails, the tool never executes. This protects both parties:| Error | Meaning | Resolution |
|---|---|---|
TOKEN_MISSING | No agent token provided | Agent must configure their token |
TOKEN_INVALID | Token doesn’t exist or is deleted | Agent must get a new token |
INSUFFICIENT_BALANCE | Agent doesn’t have enough credits | Agent must deposit more funds |
PLATFORM_UNAVAILABLE | Payo platform is down | Retry later (or use failOpen) |
Security
- Charge-before-execute: Tools only run after successful payment
- Scoped keys: Agent and provider keys have separate permissions
- No stored secrets: Raw keys are never stored, only secure hashes