@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