PayPls MCP Server

MCP (Model Context Protocol) server that enables AI agents to manage Bitcoin and USDC payments through PayPls.

🏆 Built for the Circle USDC Hackathon 2026 — View Submission

What is this?

⚠️ Important: This MCP server does NOT enforce spending limits or approval requirements. All limits are configured and enforced by the PayPls backend. Configure your limits in the PayPls Dashboard before giving agents access to real funds.

This server allows AI assistants like Claude to:

• 💰 Check wallet balances (BTC and USDC)

• 📤 Send payments with human approval

• 📥 Generate receive addresses

• 🔍 Track transaction status

All transactions can be configured to require human approval above certain thresholds, giving you control while enabling AI autonomy for small payments.

Quick Links

Installation

npm install -g @paypls/mcp-server

Or run directly with npx:

npx @paypls/mcp-server

Configuration

1. Get your API token

Sign up at paypls.io (or test.paypls.io for testnet) and generate an API token in Settings → API Keys.

2. Set environment variables

# Required: Your PayPls API token (starts with pp_)
PAYPLS_TOKEN=pp_your_token_here

# Optional: API URL (defaults to https://api.paypls.io)
# For testnet, use: https://paypls-api-dev.nfwalls.workers.dev
PAYPLS_API_URL=https://api.paypls.io

3. Configure Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "paypls": {
      "command": "npx",
      "args": ["@paypls/mcp-server"],
      "env": {
        "PAYPLS_TOKEN": "pp_your_token_here"
      }
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "paypls": {
      "command": "paypls-mcp",
      "env": {
        "PAYPLS_TOKEN": "pp_your_token_here"
      }
    }
  }
}

Available Tools

Example Usage

Once configured, you can ask Claude things like:

• "What's my Bitcoin balance?"

• "Send 10,000 sats to tb1q... for the API subscription"

• "Send $25 USDC to 0x... for the design work"

• "Generate a receive address for my wallet"

• "Check the status of transaction abc-123"

Security

• Human approval: Configure auto-approve limits in the PayPls dashboard. Transactions above the limit require explicit approval via Telegram.

• Justifications: Every send requires a justification that's logged and shown during approval.

• Bucket isolation: Use separate buckets to limit agent access to specific funds.

• Token permissions: API tokens can be scoped to specific buckets.

Handling Approval Flows

When a transaction exceeds auto-approve limits, the API returns:

{
  "status": "pending_approval",
  "transaction_id": "...",
  "message": "Awaiting human approval via Telegram",
  "expires_at": "2026-02-04T05:00:00Z"
}

Your agent should:

1. Inform the user that approval is needed

2. Optionally poll wallet_tx_status to check status

3. NOT retry the same transaction (use idempotency_key instead)

Development

# Clone the repository
git clone https://github.com/n8m8/paypls-mcp.git
cd paypls-mcp

# Install dependencies
npm install

# Run in development mode
PAYPLS_TOKEN=pp_your_token npm run dev

# Build
npm run build

# Type check
npm run typecheck

API Endpoints Used

This MCP server communicates with the PayPls Agent API:

Full API documentation: paypls.io/SKILL.md

Environment Variables

Testnet

Currently running on Bitcoin testnet (tbtc) and Ethereum Sepolia (USDC). Perfect for development and testing!

Testnet API: https://paypls-api-dev.nfwalls.workers.dev Testnet Dashboard: test.paypls.io

Support

• 📖 Integration Guide

• 🐛 Issues

License

MIT