pay-mcp

@pay-skill/mcp

MCP server for Pay -- the complete x402 payment stack for AI agents. USDC on Base.

Gives any MCP-compatible client (Claude Desktop, Cursor, VS Code, custom frameworks) the full power of Pay: direct payments, tabs, x402 paywalls, service discovery, and wallet management. No CLI binary needed.

Setup

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "pay": {
      "command": "npx",
      "args": ["-y", "@pay-skill/mcp"]
    }
  }
}

VS Code / Cursor

Add to .vscode/mcp.json:

{
  "servers": {
    "pay": {
      "command": "npx",
      "args": ["-y", "@pay-skill/mcp"]
    }
  }
}

Claude Code

claude mcp add pay -- npx -y @pay-skill/mcp

That's it. On first run, the server generates a wallet and stores it in the OS keychain (Windows Hello, macOS Keychain, Linux Secret Service). Subsequent runs load it automatically.

Configuration

Env Var	Required	Default	Description
PAYSKILL_SIGNER_KEY	No	—	Optional override. Raw hex key or .enc keystore password. Not needed for normal use.
PAY_NETWORK	No	mainnet	mainnet (Base) or testnet (Base Sepolia)

Key Resolution (checked in order)

1. OS keychain (default) — Loads from the OS credential store via keytar. On first run, a new keypair is generated and stored automatically.
2. Encrypted keystore — If ~/.pay/keys/default.enc exists, PAYSKILL_SIGNER_KEY is used as the decryption password.
3. Raw hex key — If PAYSKILL_SIGNER_KEY is a 64-char hex string, it's used directly. For dev/testing or importing an existing wallet.
4. Auto-generate — If none of the above, generates a new keypair and stores it in the OS keychain.

Diagnostic Check

Verify everything is configured correctly:

npx @pay-skill/mcp --check

Output:

pay-mcp diagnostic check
  network: Base (chain 8453)
  api:     https://pay-skill.com/api/v1
  wallet:  0x1234...
  key:     keychain
  server:  OK (router: 0xABCD...)
  auth:    OK (balance: $50.00)

All checks passed. MCP server is ready.

Tools (15)

Payments

Tool	Description
pay_send	Direct USDC payment ($1 min). Confirmation thresholds: <$10 auto, $10-100 plan, >$100 explicit.
pay_request	HTTP request with x402 auto-payment. Handles 402 detection, direct/tab settlement, price skepticism.

Tabs (metered accounts)

Tool	Description
pay_tab_open	Open pre-funded tab ($5 min, $50 recommended). Provider charges per-call.
pay_tab_close	Close tab. Returns distribution breakdown (provider 99%, fee 1%, agent remainder).
pay_tab_charge	Charge against open tab (provider only).
pay_tab_topup	Add funds to open tab (agent only).
pay_tab_list	List tabs with idle/low-balance flags.

Wallet

Tool	Description
pay_status	Balance, locked/available funds, actionable suggestions.
pay_fund	Generate 1-hour funding link (Coinbase Onramp or direct USDC).
pay_withdraw	Generate 1-hour withdrawal link.
pay_mint	Mint testnet USDC (Base Sepolia only).

Discovery & Webhooks

Tool	Description
pay_discover	Search paid API services by keyword/category.
pay_webhook_register	Register webhook for payment events (HMAC-signed).
pay_webhook_list	List registered webhooks.
pay_webhook_delete	Delete a webhook.

Resources (5)

URI	Description
pay://wallet/status	Balance, tabs, locked/available
pay://wallet/tabs	All open tabs
pay://tab/{tab_id}	Single tab detail
pay://wallet/address	Wallet address
pay://network	Network config + contract addresses

Prompts (3)

Prompt	Description
pay-for-service	Guided: discover service, evaluate pricing, make request
review-tabs	Review tabs, flag idle, suggest close/topup
fund-wallet	Generate fund link, explain deposit process

Development

git clone https://github.com/pay-skill/pay-mcp.git
cd pay-mcp
npm install
npm run build
npm test                    # unit tests (mocked)
npm run test:acceptance     # testnet (requires PAYSKILL_TESTNET_KEY)

License

MIT

Part of Pay

Pay is the complete x402 payment stack -- gateway, facilitator, SDKs, CLI, and MCP server -- that lets AI agents pay for APIs with USDC on Base.

• Documentation
• Architecture
• SDK -- Python + TypeScript
• CLI -- Command-line tool
• pay-gate -- x402 payment gateway
• Protocol -- Smart contracts