paybot-mcp

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

Install

npm install paybot-mcp paybot-sdk

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('[email protected]', '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