Skip to main content
Glama

paybot-mcp

MCP server for PayBot — payment tools for AI agents via the Model Context Protocol.

Install

npm install paybot-mcp paybot-sdk

Related 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 the paybot_register tool with the same bot id returns 409 ALREADY_EXISTS. Use paybot_register only 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

PayBot API key (see Get your API key)

(required)

PAYBOT_FACILITATOR_URL

Facilitator server URL

https://api.paybotcore.com

PAYBOT_BOT_ID

Default bot identifier

mcp-agent

PAYBOT_WALLET_KEY

Wallet private key for real payments

(optional)

PAYBOT_ENABLE_DEMO_TOOLS

Register the governed mock demo tools (delete_database, annotate_record). Must be exactly true.

false (off)

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

paybot_pay

Make a payment (USDC by default; supports alternate tokens + idempotency)

paybot_balance

Check trust level, spending limits, and remaining budget

paybot_history

View recent payment history and audit events

paybot_register

Register a new bot with the facilitator (optional idempotency key)

paybot_list_networks_and_tokens

Discover supported networks and tokens (offline, no API key)

paybot_health_extended

Extended facilitator health (status/version/uptime + extras)

paybot_set_spending_limit

Set per-transaction / daily / hourly limits and a recipient allowlist

paybot_commission_inspect

Inspect commission summary and a filterable ledger

paybot_pool_create

Create an in-process bot pool with an optional shared treasury

paybot_pool_allocate

Add a bot to a pool, optionally paying as it through the treasury

paybot_pool_revoke

Remove a bot from a pool

paybot_pool_status

Report pool treasury and per-bot spend counters

paybot_pay

Param

Type

Notes

amount

string

Amount in USD (e.g., "0.05")

recipient

string

Recipient wallet address (0x...)

resource

string

URL or description of what you're paying for

botId?

string

Bot identifier (defaults to env)

network?

string

Network CAIP-2 ID (default: Base Sepolia)

token?

string

Token ticker (default USDC); e.g. USDC, EURC, DAI

idempotencyKey?

string

Repeat call with the same key returns the cached result

paybot_balance

Param

Type

Notes

botId?

string

Bot identifier (defaults to env)

paybot_history

Param

Type

Notes

botId?

string

Bot identifier (defaults to env)

limit?

number

Max events to return (default: 10)

paybot_register

Param

Type

Notes

botId

string

Unique bot identifier

trustLevel?

number

Initial trust level 0-5 (default: 1)

idempotencyKey?

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

botId?

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

botId?

string

Bot identifier (defaults to env)

maxTransactionUsd?

number

Max USD per transaction

maxDailySpendUsd?

number

Max USD spend per day

maxTransactionsPerHour?

number

Max transactions per hour

allowedRecipients?

string[]

Allowlist of recipient addresses

paybot_commission_inspect

Param

Type

Notes

botId?

string

Bot identifier (defaults to env)

status?

enum

Filter ledger by pending | forwarded | deferred

startDate?

string

Ledger start date (ISO 8601)

endDate?

string

Ledger end date (ISO 8601)

limit?

number

Max ledger entries (default: 50)

offset?

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

poolId

string

Identifier for this pool (used by allocate/revoke/status)

sharedDailyLimitUsd?

number

Optional shared daily spend cap across all bots

paybot_pool_allocate

Param

Type

Notes

poolId

string

Pool identifier

botId

string

Bot identifier to add to the pool

trustLevel?

number

Initial trust level 0-5

pay?

object

Optional { amount, recipient, resource, network?, token? } to pay as this bot

paybot_pool_revoke

Param

Type

Notes

poolId

string

Pool identifier

botId

string

Bot identifier to remove

paybot_pool_status

Param

Type

Notes

poolId

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:

  1. builds an ActionIntentverb = 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';

  2. calls core POST /actions/govern;

  3. 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 block mode) polls GET /approvals/:id with backoff until approved/denied/expired or approvalTimeoutMs (default 120 s); on approval it re-verifies params_hash AND requires the approval to be action-shaped before executing (TOCTOU + cross-route defence), then runs once. (return mode hands back the approval_id instead.)

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/approve route, whose grant path attempts settlement. The approval row is the shared A5a store, so a payment-route approve still flips it to APPROVED; the interceptor therefore does not trust a bare decision === 'APPROVED'. The payment approve route always runs settlement and writes a state (SETTLE_FAILED / RESUME_CONTEXT_UNAVAILABLE for an action); the action route never settles and writes no state. The interceptor executes only when the approved row has no settlement state — a present state is treated as a payment-route claim and the call fails closed with WRONG_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. A reversible tool MAY set failOpen: 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_hash and the extractor's target_ref are 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

delete_database

irreversible

MOCK — touches nothing; pauses for human approval, then returns a labelled mock confirmation

annotate_record

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

Apache 2.0

Available Tools

4 tools
get_paymentC

Get the status of a PayBot payment

ParametersJSON Schema
NameRequiredDescriptionDefault
paymentIdYesThe payment ID to look up

TDQS

C2.9/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters4/5

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.

Purpose4/5

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.

Usage Guidelines3/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax number of payments to return
offsetNoOffset for pagination

TDQS

C2.9/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
toYesRecipient wallet address (0x...)
amountYesAmount in USDC (e.g. "10.00")
memoNoPayment description
idempotencyKeyNoIdempotency key to prevent duplicates

TDQS

C2.9/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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

A3.5/5.0
Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivityMaintained
ResponsivenessSyncing

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

Related MCP Servers

  • A
    license
    B
    quality
    D
    maintenance
    Payment & Transaction Tools that allow AI agents to send, receive, and request payments
    11
    32
    2
    Apache 2.0
  • A
    license
    A
    quality
    D
    maintenance
    Enables 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.
    6
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Integrates PayU payment services with AI tools through the Model Context Protocol, enabling payment link creation, transaction retrieval, and settlement analysis.
    MIT

Latest Blog Posts

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