@useagentpay/mcp-server

@useagentpay/mcp-server

MCP server for AgentPay — exposes the full payment lifecycle to any MCP-compatible AI host (Claude Desktop, Cursor, Claude Code, Windsurf).

9 tools, 3 resources, 3 prompts. Agents can propose purchases, wait for human approval, execute checkout, and retrieve receipts — all over the Model Context Protocol.

Install & Setup

npx -p @useagentpay/mcp-server agentpay init     # creates agentpay/ folder with AGENT.md
npx -p @useagentpay/mcp-server agentpay setup    # opens browser to enter card, set budget & limits

Host Configuration

Add to your Claude Desktop, Cursor, or Claude Code config:

{
  "mcpServers": {
    "agentpay": {
      "command": "npx",
      "args": ["-p", "@useagentpay/mcp-server", "agentpay", "serve"]
    }
  }
}

With passphrase (for execute)

{
  "mcpServers": {
    "agentpay": {
      "command": "npx",
      "args": ["-p", "@useagentpay/mcp-server", "agentpay", "serve"],
      "env": {
        "AGENTPAY_PASSPHRASE": "your-passphrase"
      }
    }
  }
}

Mobile Mode

Enable mobile mode to approve purchases from your phone via Cloudflare Tunnel. No Cloudflare account needed — requires cloudflared installed on the system.

# Enable mobile mode
npx -p @useagentpay/mcp-server agentpay mobile on

# With notification (how the approval link reaches your phone)
npx -p @useagentpay/mcp-server agentpay mobile on --notify-command "your-send-command {{url}}"
npx -p @useagentpay/mcp-server agentpay mobile on --notify-webhook "https://hooks.example.com/notify"

# Disable mobile mode
npx -p @useagentpay/mcp-server agentpay mobile off

When mobile mode is on, agents call agentpay_request_mobile_approval instead of opening the local dashboard. This starts a Cloudflare Quick Tunnel and sends a temporary HTTPS approval link to the configured notification endpoint.

Install cloudflared

• macOS: brew install cloudflared
• Linux: Download
• Windows: winget install Cloudflare.cloudflared

Tools

Tool	Description
agentpay_status	Check setup state, balance, budget, mobileMode, pending count
agentpay_check_balance	Current balance and limits (call before proposing)
agentpay_list_pending	Pending transactions awaiting approval
agentpay_propose_purchase	Propose a new purchase (merchant, amount, description, url)
agentpay_request_mobile_approval	Tunnel a secure approval link to the user's phone
agentpay_get_transaction	Get transaction details by ID
agentpay_wait_for_approval	Long-poll until approved or rejected
agentpay_execute_purchase	Execute an approved purchase (requires passphrase config)
agentpay_get_receipt	Get receipt for a completed purchase

Resources

URI	Description
agentpay://wallet	Wallet balance and limits
agentpay://transactions/{txId}	Transaction details
agentpay://audit-log	Last 50 audit log entries

Prompts

Name	Description
buy	Guided step-by-step purchase flow
budget-check	Balance and pending transaction summary
purchase-status	Recent transaction history

Typical Agent Flow

1. agentpay_status                    → verify setup, check mobileMode
2. agentpay_check_balance             → confirm budget for purchase
3. agentpay_propose_purchase          → create pending transaction
4. agentpay_request_mobile_approval   → (if mobileMode: true) send link to phone
   OR open dashboard                  → (if mobileMode: false) open browser
5. agentpay_wait_for_approval         → wait for human to approve
6. agentpay_execute_purchase          → run checkout via headless browser
7. agentpay_get_receipt               → retrieve confirmation

Passphrase Modes

The execute_purchase tool needs access to the vault passphrase. Three modes:

Mode	Config	Description
env	AGENTPAY_PASSPHRASE	Passphrase from environment variable
server	AGENTPAY_PASSPHRASE_SERVER	Fetch passphrase from a URL
none	Neither set	Read-only — propose/approve works, execute does not

Environment Variables

Variable	Purpose	Default
AGENTPAY_PASSPHRASE	Passphrase for execute (env mode)	—
AGENTPAY_PASSPHRASE_SERVER	URL to fetch passphrase (server mode)	—
AGENTPAY_NOTIFY_COMMAND	Override notify command for mobile mode	—
AGENTPAY_NOTIFY_WEBHOOK	Override notify webhook for mobile mode	—
ANTHROPIC_API_KEY	LLM API key for browser navigation	—
AGENTPAY_HOME	Override data directory	./agentpay
MCP_TRANSPORT	Set to http for HTTP transport	stdio
MCP_HTTP_PORT	HTTP port	3100

License

MIT