PayBot MCP Server
The PayBot MCP Server enables AI agents to manage USDC payments and bot finances programmatically through the Model Context Protocol.
Make a Payment (
pay): Submit a USDC payment to a recipient wallet address, specifying an amount, optional memo/description, idempotency key (to prevent duplicates), bot identifier, and network.Check Payment Status (
get_payment): Retrieve the current status and details of a specific payment by its payment ID.List Recent Payments (
list_payments): View a paginated list of recent payments and audit events, with control over result count and offset.Check Bot Balance & Limits : Query a bot's trust level, spending limits, and remaining budget.
Register New Bots: Register a new bot with the facilitator using a unique identifier and optional initial trust level.
Health Check (
health): Verify that the PayBot server is reachable and operational.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@PayBot MCP Server Send 25 USDC to 0x742d35Cc6634C0532925a3b844Bc454e4438f44e for the consultation."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
paybot-mcp
MCP server for PayBot — payment tools for AI agents via the Model Context Protocol.
Install
npm install paybot-mcp paybot-sdkRelated MCP server: InventPay MCP Server
Get your API key
PAYBOT_API_KEY is required — without it every tool call fails with a 401. The fastest way to get a key is one PayBotClient.signup() call (from paybot-sdk) against the hosted facilitator at https://api.paybotcore.com:
node -e "import('paybot-sdk').then(async ({ PayBotClient }) => {
const a = await PayBotClient.signup('you@example.com', 'a-strong-password', { botId: 'my-agent' });
console.log(a.apiKey); // pb_live_... — printed ONLY once, save it now
})"This single call registers your operator account, creates the API key, and registers the bot (botId). Put the printed key into PAYBOT_API_KEY in the MCP config below, and reuse the same bot id as PAYBOT_BOT_ID.
Notes:
The key is printed only once — store it securely; it cannot be retrieved later.
Because
signup()already registered your bot, calling thepaybot_registertool with the same bot id returns409 ALREADY_EXISTS. Usepaybot_registeronly for additional bots.Full auth flow (login, extra API keys, self-hosted facilitators): see the paybot-sdk README → Get your API key.
Usage with Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"paybot": {
"command": "npx",
"args": ["paybot-mcp"],
"env": {
"PAYBOT_API_KEY": "pb_...",
"PAYBOT_FACILITATOR_URL": "https://api.paybotcore.com",
"PAYBOT_BOT_ID": "my-agent"
}
}
}
}Usage with Claude Code
{
"mcpServers": {
"paybot": {
"command": "npx",
"args": ["paybot-mcp"],
"env": {
"PAYBOT_API_KEY": "pb_...",
"PAYBOT_BOT_ID": "my-agent"
}
}
}
}Environment Variables
Variable | Description | Default |
| PayBot API key (see Get your API key) | (required) |
| Facilitator server URL |
|
| Default bot identifier |
|
| Wallet private key for real payments | (optional) |
| Register the governed mock demo tools ( |
|
If PAYBOT_API_KEY is unset or empty, the server still boots (so the MCP handshake succeeds) but prints a warning to stderr at startup, and every tool call will fail with an authentication error until a key is configured. Omitting PAYBOT_WALLET_KEY keeps the underlying SDK in mock mode (no on-chain settlement).
Available Tools
Tool | Description |
| Make a payment (USDC by default; supports alternate tokens + idempotency) |
| Check trust level, spending limits, and remaining budget |
| View recent payment history and audit events |
| Register a new bot with the facilitator (optional idempotency key) |
| Discover supported networks and tokens (offline, no API key) |
| Extended facilitator health (status/version/uptime + extras) |
| Set per-transaction / daily / hourly limits and a recipient allowlist |
| Inspect commission summary and a filterable ledger |
| Create an in-process bot pool with an optional shared treasury |
| Add a bot to a pool, optionally paying as it through the treasury |
| Remove a bot from a pool |
| Report pool treasury and per-bot spend counters |
paybot_pay
Param | Type | Notes |
| string | Amount in USD (e.g., |
| string | Recipient wallet address ( |
| string | URL or description of what you're paying for |
| string | Bot identifier (defaults to env) |
| string | Network CAIP-2 ID (default: Base Sepolia) |
| string | Token ticker (default |
| string | Repeat call with the same key returns the cached result |
paybot_balance
Param | Type | Notes |
| string | Bot identifier (defaults to env) |
paybot_history
Param | Type | Notes |
| string | Bot identifier (defaults to env) |
| number | Max events to return (default: 10) |
paybot_register
Param | Type | Notes |
| string | Unique bot identifier |
| number | Initial trust level 0-5 (default: 1) |
| string | Repeat register with the same key returns the cached result |
paybot_list_networks_and_tokens
Read-only discovery. Requires no API key and makes zero network calls. Surfaces only the public open-core registry — operator-private mainnet addresses are never shown (e.g. EURC advertises its Base Sepolia testnet deployment only).
No parameters.
paybot_health_extended
Param | Type | Notes |
| string | Bot identifier (defaults to env) |
Returns status, version, uptime, timestamp, plus any extra fields the
facilitator reports.
paybot_set_spending_limit
Tightens an agent's own limits. The facilitator enforces the operator ceiling and may reject attempts to loosen beyond policy.
Param | Type | Notes |
| string | Bot identifier (defaults to env) |
| number | Max USD per transaction |
| number | Max USD spend per day |
| number | Max transactions per hour |
| string[] | Allowlist of recipient addresses |
paybot_commission_inspect
Param | Type | Notes |
| string | Bot identifier (defaults to env) |
| enum | Filter ledger by |
| string | Ledger start date (ISO 8601) |
| string | Ledger end date (ISO 8601) |
| number | Max ledger entries (default: 50) |
| number | Ledger pagination offset |
paybot_pool_create
Creates an in-process bot pool for this MCP session. Treasury accounting is in-memory; the facilitator remains the authoritative limit.
Param | Type | Notes |
| string | Identifier for this pool (used by allocate/revoke/status) |
| number | Optional shared daily spend cap across all bots |
paybot_pool_allocate
Param | Type | Notes |
| string | Pool identifier |
| string | Bot identifier to add to the pool |
| number | Initial trust level 0-5 |
| object | Optional |
paybot_pool_revoke
Param | Type | Notes |
| string | Pool identifier |
| string | Bot identifier to remove |
paybot_pool_status
Param | Type | Notes |
| string | Pool identifier |
Governed tools (decide-before / prove-after)
PayBot MCP can wrap any tool — not just payments — so a dangerous call must pass policy before it runs, an irreversible call pauses for a named human's approval, and every outcome leaves a tamper-evident, replayable trace in core's audit chain. This is the kill-switch + black-box-recorder for MCP tool calls.
How it works
registerGovernedTool(server, def, client, opts) is a higher-order registrar.
Each wrapped call:
builds an ActionIntent —
verb= tool name,target_ref= a registrar-provided extractor over the args (opaque, never raw PII),params_hash= SHA-256 of the canonical (key-sorted) JSON of the args,actor.subject_ref= the configured bot id,channel: 'mcp';calls core
POST /actions/govern;acts on the verdict:
allow → runs the tool, and appends
executed: params_hash=…, result_hash=…to the output so the trace binds intent → execution;deny → does not run; returns the gate reasons;
pending → (default
blockmode) pollsGET /approvals/:idwith backoff until approved/denied/expired orapprovalTimeoutMs(default 120 s); on approval it re-verifiesparams_hashAND requires the approval to be action-shaped before executing (TOCTOU + cross-route defence), then runs once. (returnmode hands back theapproval_idinstead.)
Approve via the ACTION route — enforced, not just advised. A paused action is approved/denied through
POST /actions/approvals/:id/approve(or.../deny) — not the payment/approvals/:id/approveroute, whose grant path attempts settlement. The approval row is the shared A5a store, so a payment-route approve still flips it toAPPROVED; the interceptor therefore does not trust a baredecision === 'APPROVED'. The payment approve route always runs settlement and writes astate(SETTLE_FAILED/RESUME_CONTEXT_UNAVAILABLEfor an action); the action route never settles and writes nostate. The interceptor executes only when the approved row has no settlementstate— a presentstateis treated as a payment-route claim and the call fails closed withWRONG_APPROVAL_ROUTE(handler never runs). This closes the cross-route hazard where a human approving what they believe is a payment would otherwise authorize an agent's irreversible action.
Cost & lifetime
Governance adds one network round-trip per governed call (/actions/govern).
A pending action in block mode holds open only as long as the stdio session
lives — MCP stdio servers are single-session, so a session that ends drops a
blocking wait. Operators drive approval from a second terminal (curl/dashboard),
exactly like the HITL payment demo.
Security properties
Fail closed. If governance is unreachable (network error, timeout, 5xx, malformed body) an irreversible or unknown action is refused (
GOVERNANCE_UNREACHABLE) — an unreachable governor never silently allows. Areversibletool MAY setfailOpen: true(demo-only convenience; ignored for irreversible verbs).Risk class is set by the registrar (operator code), never by the model. An agent cannot self-declare its destructive tool "reversible."
No raw args leave the process. Only the
params_hashand the extractor'starget_refare sent to core; raw arguments (connection strings, PII) stay local.No bypass. Governance is applied at registration. A server that registers a raw tool is ungoverned by definition — we govern what is wrapped, and make no claim to intercept everything.
Demo tools (off by default)
Set PAYBOT_ENABLE_DEMO_TOOLS=true to register two mock governed tools:
Tool | Risk class | Effect |
| irreversible | MOCK — touches nothing; pauses for human approval, then returns a labelled mock confirmation |
| reversible | MOCK — proves the allow path; flows straight through |
A published MCP server must not advertise a delete_database tool to every
agent, so these stay off unless the flag is explicitly true.
See docs/runbooks/governed-action-demo.md
for the exact recorded-demo script (govern → pending → approve → mock execute →
replayable audit proof).
Programmatic Usage
import { createMcpServer } from 'paybot-mcp/server';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
const server = createMcpServer();
const transport = new StdioServerTransport();
await server.connect(transport);License
Available Tools
4 toolsget_paymentC
Get the status of a PayBot payment
Inputs: paymentId (required).
healthA
Check if the PayBot server is reachable
Inputs: no named parameters.
list_paymentsC
List recent payments
Inputs: limit, offset.
payC
Submit a USDC payment through PayBot
Inputs: to (required), amount (required), memo, idempotencyKey.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose with no overlap: get_payment retrieves a specific payment status, health checks server reachability, list_payments shows recent payments, and pay submits a new payment. The actions and targets are well-defined and unlikely to cause confusion.
All tool names follow a consistent snake_case pattern with clear verb_noun combinations: get_payment, health (implied verb 'check'), list_payments, and pay (simple verb). The naming is predictable and readable throughout the set.
With 4 tools, this server is well-scoped for handling payments via PayBot. Each tool serves a distinct and essential function (check health, list, get, and create payments), and there are no extraneous or missing tools for this domain.
The toolset covers core payment operations: health monitoring, listing, retrieving, and creating payments. A minor gap exists in update or cancel operations for payments, but agents can likely work around this given the focused scope on USDC payments through PayBot.
Maintenance
Related MCP Connectors
USDC wallets, payment links and x402 payments on Solana for AI agents.
Pay for APIs with USDC. Read-only x402 payment discovery, verification, evidence, and status.
17 pay-per-call web, finance, legal and onchain tools for AI agents. USDC on Base via x402/MPP.
Payment infrastructure for AI agents: spending rules, approval flows, single-use virtual cards.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to manage Bitcoin and USDC payments by checking balances, sending funds, and generating receive addresses through the PayPls platform. It facilitates secure financial automation with features like transaction tracking and configurable human approval limits.6MIT
- AlicenseAqualityDmaintenanceEnables AI agents to manage crypto payments, stores, products, and orders through the Model Context Protocol.2047 npmMIT

paean-pay-mcpofficial
AlicenseNot gradedqualityDmaintenanceEnables AI agents to send and receive USDC stablecoin payments on Base and Solana blockchains through MCP tools for wallet operations, balance checks, payment requests, and transfers.23 npm7MIT- AlicenseAqualityCmaintenanceEnables AI agents to quote, authorize, submit, and verify agent-to-agent USDC payments on Base through standard MCP tools over stdio.4316 npmBusiness Source 1.1