What can you do with this server?

The PayPls MCP Server enables AI agents to manage Bitcoin and USDC payments through the PayPls platform with configurable human approval controls. Core Capabilities: * Check wallet balances - View BTC (in satoshis) and USDC (in dollars) balances with USD equivalents across different wallet buckets * List wallet buckets - See all accessible buckets with their balances and auto-approve limits for both BTC and USDC * Send payments - Transfer Bitcoin to addresses (amount in satoshis) or USDC to EVM addresses (amount in dollars), both requiring justification * Generate receive addresses - Get deposit addresses for receiving BTC or USDC into specific wallet buckets * Track transaction status - Monitor payment status using transaction IDs, including pending approvals and completion states Security & Control Features: * Human approval workflows via Telegram for transactions exceeding auto-approve thresholds * Bucket isolation to restrict agent access to specific fund pools * Scoped API tokens for granular permissions and access control * Required justifications for all payments, presented during approval * Testnet support on Bitcoin testnet (tbtc) and Ethereum Sepolia for safe development

Which integrations are available for this server?

Enables managing Bitcoin payments, including checking balances, sending BTC to specific addresses, generating receive addresses, and tracking transaction status.

How do I use PayPls MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@PayPls MCP Server Send $25 USDC to 0x742d35Cc6634C0532925a3b844Bc454 for the design work" 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.

PayPls MCP Server

MIT License npm version Circle USDC Hackathon 2026

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

Resource	URL
🌐 Landing Page	paypls.io
🧪 Testnet Dashboard	test.paypls.io
📡 API (Production)	api.paypls.io
📖 Integration Guide	paypls.io/SKILL.md
🏆 Hackathon Submission	Moltbook
💻 Source Code	GitHub

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

Tool	Description
`wallet_balance`	Check BTC or USDC balance of your wallet
`wallet_send_btc`	Send Bitcoin to an address
`wallet_send_usdc`	Send USDC to an EVM address
`wallet_receive`	Get an address to receive funds
`wallet_tx_status`	Check transaction status

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:

Inform the user that approval is needed
Optionally poll wallet_tx_status to check status
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:

MCP Tool	API Endpoint
`wallet_balance`	`GET /agent/balance`
`wallet_send_btc`	`POST /agent/send`
`wallet_send_usdc`	`POST /agent/send`
`wallet_receive`	`POST /agent/receive`
`wallet_tx_status`	`GET /agent/tx/:id`