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 "Install 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 ServerSend 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: PayPls 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
| Name | Required | Description | Default |
|---|---|---|---|
| paymentId | Yes | The payment ID to look up |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool retrieves payment status, implying a read-only operation, but doesn't clarify if it requires authentication, has rate limits, or what the response format might be. This is a significant gap for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded and easy to parse, though it could be slightly more informative by including usage context without sacrificing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., status details, error handling) or behavioral aspects like authentication needs. For a tool with no structured data beyond the input schema, more context is needed to be fully helpful to an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'paymentId' parameter fully documented in the schema. The description doesn't add any meaning beyond what the schema provides, such as format examples or constraints. Since schema coverage is high, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Get') and resource ('status of a PayBot payment'), making it immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'list_payments' or 'pay', which would require mentioning this is for retrieving a single payment's status rather than listing multiple payments or initiating a payment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'list_payments' for multiple payments or 'pay' for initiating payments, nor does it specify prerequisites such as needing a payment ID. This leaves the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
healthA
Check if the PayBot server is reachable
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the tool's core behavior (reachability check) but doesn't specify what 'reachable' means (e.g., network connectivity, service status), expected response format, timeout behavior, or authentication requirements. For a zero-parameter tool, this is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It's front-loaded with the essential information and appropriately sized for a simple health check tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter health check tool with no annotations and no output schema, the description provides the basic purpose but lacks details about what constitutes 'reachable', expected response format, or error conditions. Given the tool's simplicity, it's minimally complete but could benefit from slightly more behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters with 100% schema description coverage. The description appropriately doesn't discuss parameters since none exist. It focuses on the tool's purpose rather than parameter details, which is correct for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as checking server reachability with a specific verb ('Check') and resource ('PayBot server'). It distinguishes from siblings like get_payment, list_payments, and pay by focusing on health monitoring rather than payment operations. However, it doesn't explicitly contrast with potential alternative health-check tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context - when you need to verify server availability before attempting payment operations. It doesn't provide explicit when-to-use vs. when-not-to-use guidance or name alternatives, but the context is reasonably clear given the sibling tools are all payment-related.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_paymentsC
List recent payments
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max number of payments to return | |
| offset | No | Offset for pagination |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. 'List recent payments' implies a read-only operation but doesn't specify permissions, rate limits, pagination behavior beyond the schema parameters, or what 'recent' means (e.g., time window). This leaves significant gaps for a tool with two parameters and no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient phrase with zero wasted words. It's front-loaded with the core purpose and appropriately sized for a simple listing tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no annotations, no output schema), the description is incomplete. It doesn't explain what 'recent' entails, the format of returned payments, or how pagination works in practice. For a listing tool with no structured behavioral hints, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with clear documentation for 'limit' and 'offset'. The description adds no additional parameter semantics beyond implying 'recent' filtering, which isn't reflected in the parameters. Since the schema does the heavy lifting, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List recent payments' clearly states the verb ('List') and resource ('payments'), and the qualifier 'recent' adds useful scope. However, it doesn't explicitly differentiate from sibling tools like 'get_payment' (which likely retrieves a single payment) or 'pay' (which likely initiates a payment), so it falls short of a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get_payment' or 'pay'. It lacks any context about prerequisites, exclusions, or typical use cases, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
payC
Submit a USDC payment through PayBot
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Recipient wallet address (0x...) | |
| amount | Yes | Amount in USDC (e.g. "10.00") | |
| memo | No | Payment description | |
| idempotencyKey | No | Idempotency key to prevent duplicates |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action is to 'Submit a USDC payment', implying a write operation, but fails to mention critical details such as required permissions, transaction confirmation, error handling, or rate limits, leaving significant gaps in understanding the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence that efficiently conveys the core functionality without any unnecessary words. It is appropriately sized and front-loaded, making it easy to grasp immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a payment submission tool with no annotations and no output schema, the description is insufficient. It lacks details on return values, error conditions, security requirements, and how it interacts with sibling tools, making it incomplete for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, providing clear documentation for all parameters (to, amount, memo, idempotencyKey). The description adds no additional parameter semantics beyond what the schema already covers, so it meets the baseline for adequate but not enhanced parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Submit a USDC payment') and specifies the mechanism ('through PayBot'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'get_payment' or 'list_payments', which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like 'get_payment' or 'list_payments'. The description lacks context about prerequisites, error conditions, or typical use cases, offering minimal usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
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
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Payment infrastructure for AI agents: spending rules, approval flows, single-use virtual cards.
Real-time data feeds for AI agents with USDC micropayments on Base for premium tools.
Verified, pay-per-use API tools for AI agents through one authenticated connection.
Payment rails for AI agents. Pay merchants in USDC on Base. Dual-protocol: x402 + OKX APP.
Related MCP Servers
- AlicenseBqualityDmaintenancePayment & Transaction Tools that allow AI agents to send, receive, and request payments11322Apache 2.0
- 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

payu-mcp-serverofficial
AlicenseNot gradedqualityDmaintenanceIntegrates PayU payment services with AI tools through the Model Context Protocol, enabling payment link creation, transaction retrieval, and settlement analysis.MIT- AlicenseAqualityCmaintenanceEnables AI agents to manage crypto payments, stores, products, and orders through the Model Context Protocol.20223MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/RBKunnela/paybot-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server