paybot-mcp
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 pay 0.05 USDC to 0x742d35Cc6634C0532925a3b844Bc454e4438f44e for API access"
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: remit.md 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
12 toolspaybot_balanceB
Check spending limits, trust level, and remaining daily budget for a bot.
Inputs: botId.
paybot_commission_inspectB
Inspect commission for transparency: aggregate summary (totals + rate) and a filterable, paginated ledger.
Inputs: botId, limit, offset, status, +2 more.
paybot_health_extendedB
Check extended facilitator health: status, version, uptime, timestamp, plus any extra fields the facilitator reports (e.g. relayer/gas/AML status).
Inputs: botId.
paybot_historyB
View recent payment history and audit events for a bot.
Inputs: botId, limit.
paybot_list_networks_and_tokensA
List the networks and tokens PayBot supports. Read-only, offline, requires no API key. Surfaces only the PUBLIC open-core registry — operator-private mainnet addresses are never shown.
Inputs: no named parameters.
paybot_payB
Make a payment (USDC by default) for an API, service, or resource. Returns transaction hash and commission breakdown. Supports alternate tokens and idempotency.
Inputs: amount (required), resource (required), recipient (required), botId, +3 more.
paybot_pool_allocateB
Add a bot to a pool, and optionally make a payment as that bot through the shared treasury.
Inputs: botId (required), poolId (required), pay, trustLevel.
paybot_pool_createB
Create an in-process bot pool with an optional shared daily treasury. The pool lives for this MCP session; treasury accounting is in-memory and the facilitator remains authoritative.
Inputs: poolId (required), sharedDailyLimitUsd.
paybot_pool_revokeC
Remove a bot from a pool.
Inputs: botId (required), poolId (required).
paybot_pool_statusB
Report a pool's remaining shared treasury and per-bot local spend/transaction counters (in-process projection; facilitator is authoritative).
Inputs: poolId (required).
paybot_registerA
Register a new bot with the PayBot facilitator. Returns the assigned trust level. Supports an optional idempotency key for safe re-issue.
Inputs: botId (required), trustLevel, idempotencyKey.
paybot_set_spending_limitA
Set spending limits for a bot. Tightens the agent's own limits; the facilitator enforces the operator ceiling and may reject attempts to loosen beyond policy.
Inputs: botId, maxDailySpendUsd, allowedRecipients, maxTransactionUsd, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Most tools target distinct resources: bot-level operations (balance, pay, history, register, set_spending_limit) are clearly separated from pool operations (pool_create, pool_allocate, pool_status, pool_revoke). Minor potential overlap between paybot_history and paybot_commission_inspect (both surface ledger-like data), and paybot_pool_allocate includes an optional payment that touches paybot_pay's domain, but descriptions make boundaries clear enough.
All tools share the paybot_ prefix and use snake_case throughout. There is a mild inconsistency in ordering: some are verb_noun (list_networks_and_tokens, set_spending_limit, pool_create), while others are bare nouns (balance, pay, history, register, health_extended), but the convention remains predictable and readable.
12 tools is well-scoped for a payment bot server covering registration, payments, limits, history, commissions, health, and pool management. Each tool appears to earn its place with no obvious redundancy or padding.
Core lifecycle is covered: register, pay, check balance, view history, set limits, inspect commissions, and manage pools. Gaps include no bot deregistration/unregister (pool_revoke only removes from a pool) and no dedicated bot detail/profile lookup beyond balance, but these are minor and workable.
Maintenance
Related MCP Connectors
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
17 pay-per-call web, finance, legal and onchain tools for AI agents. USDC on Base via x402/MPP.
Marketplace and payment rail for AI agents: list, buy and settle with signed receipts.
Paid MCP tools behind one endpoint. Agents pay per call in USDC on Base via x402.
Related MCP Servers
- AlicenseAqualityBmaintenanceConnects AI agents to the PayBot payment infrastructure, enabling automated USDC transactions and payment status management. It provides tools for submitting payments, tracking transaction histories, and monitoring payment IDs via the Model Context Protocol.414 npmApache 2.0
- AlicenseNot gradedqualityFmaintenanceEnables AI agents to perform financial transactions such as direct payments, escrows, and bounty management using natural language with zero code integration. It provides a comprehensive suite of tools for fund streaming, subscriptions, and reputation tracking to facilitate secure agent-to-agent commerce.MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI models to manage escrow payments, account monitoring, and blockchain-verified transactions through the Model Context Protocol.1-
- AlicenseAqualityDmaintenanceEnables AI agents to manage crypto payments, stores, products, and orders through the Model Context Protocol.2047 npmMIT