Skip to main content

​
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:
1

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.
2

SDK intercepts the call

The withPayments() wrapper intercepts the request before the tool executes.
3

SDK checks pricing

The SDK looks up the tool’s price. If price is 0, the tool executes immediately (no charge).
4

SDK charges the agent

For paid tools, the SDK calls the Payo platform with the agent token, tool name, and price.
5

Platform validates and transfers

Payo validates both keys, checks the agent’s balance, and transfers funds from the agent to the provider.
6

Tool executes

If the charge succeeds, the tool runs and returns its result to the agent.

​
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
This ensures money is never created or destroyed, every transaction is logged, and partial transfers are impossible.

​
Authentication

Payo uses two types of keys:
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:
Standard HTTP header. Used by most MCP clients.

​
Error Handling

When a charge fails, the tool never executes. This protects both parties:

​
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