@pincerpay/mcp

MCP server for PincerPay — on-chain USDC payment gateway for AI agents using the x402 protocol.

Works with Claude, Cursor, Windsurf, GitHub Copilot, Replit, and any MCP-compatible client.

Quick Start

Claude Code

claude mcp add pincerpay -- npx -y @pincerpay/mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "pincerpay": {
      "command": "npx",
      "args": ["-y", "@pincerpay/mcp"],
      "env": {
        "PINCERPAY_API_KEY": "pp_live_your_key_here"
      }
    }
  }
}

Cursor

Settings > Tools & MCP > Add Server:

{
  "mcpServers": {
    "pincerpay": {
      "command": "npx",
      "args": ["-y", "@pincerpay/mcp"],
      "env": {
        "PINCERPAY_API_KEY": "pp_live_your_key_here"
      }
    }
  }
}

Windsurf

Add via the Cascade MCP panel or mcp.json:

{
  "mcpServers": {
    "pincerpay": {
      "command": "npx",
      "args": ["-y", "@pincerpay/mcp"],
      "env": {
        "PINCERPAY_API_KEY": "pp_live_your_key_here"
      }
    }
  }
}

Remote (Streamable HTTP)

npx @pincerpay/mcp --transport=http --port=3100 --api-key=pp_live_your_key

Tools (20)

Monitoring & Discovery

| Tool | Description | Auth Required | |------|-------------|:---:| | list-supported-chains | List supported chains and USDC configs | No | | estimate-gas-cost | Estimate gas fees per chain | No | | check-facilitator-health | Check facilitator connectivity and worker status | No | | get-settlement-metrics | Fetch performance metrics (latency, counters, error rates) | No |

Operations

| Tool | Description | Auth Required | |------|-------------|:---:| | check-transaction-status | Query transaction status by hash/signature | Yes | | verify-payment | Dry-run payment validation without broadcasting | Yes | | list-transactions | List transactions with filtering and pagination | Yes |

Paywall CRUD

| Tool | Description | Auth Required | |------|-------------|:---:| | list-paywalls | List paywalled endpoints | Yes | | create-paywall | Create a new paywalled endpoint | Yes | | update-paywall | Update paywall price, status, or chains | Yes | | delete-paywall | Permanently delete a paywall | Yes |

Agent Management

| Tool | Description | Auth Required | |------|-------------|:---:| | list-agents | List agents that have interacted with your account | Yes | | update-agent | Update agent name, status, or spending limits | Yes |

Webhook Observability

| Tool | Description | Auth Required | |------|-------------|:---:| | list-webhooks | List webhook delivery attempts | Yes | | retry-webhook | Retry a failed webhook delivery | Yes |

Account

| Tool | Description | Auth Required | |------|-------------|:---:| | get-merchant-profile | Fetch merchant profile and configuration | Yes |

Scaffolding & Validation

| Tool | Description | Auth Required | |------|-------------|:---:| | validate-payment-config | Validate merchant config with route pattern checks | No | | scaffold-x402-middleware | Generate Express/Hono/Next.js middleware | No | | scaffold-agent-client | Generate agent fetch wrapper with spending policies | No | | generate-ucp-manifest | Create commerce discovery manifest | No |

Resources

| Resource | URI | Description | |----------|-----|-------------| | Chain configs | chain://{shorthand} | Config for any of the 6 supported chains | | OpenAPI spec | pincerpay://openapi | Live facilitator OpenAPI spec | | Documentation | docs://pincerpay/{topic} | Embedded docs (5 topics — see below) |

Doc Topics

| Topic | URI | Content | |-------|-----|---------| | Getting Started | docs://pincerpay/getting-started | Prerequisites, Choose Your Path (merchant vs agent), devnet/mainnet, key concepts | | Merchant Guide | docs://pincerpay/merchant | Express, Hono, and Next.js middleware setup, multi-chain routes, config reference | | Agent Guide | docs://pincerpay/agent | Agent setup, spending policies (base units), runtime management, properties | | Troubleshooting | docs://pincerpay/troubleshooting | Common issues table, devnet funding, debugging tips | | Reference | docs://pincerpay/reference | Chain shorthands, USDC amounts, package exports, API methods |

Prompts (6)

| Prompt | Description | |--------|-------------| | get-started | Interactive onboarding — determines your role and guides you to the right flow | | integrate-merchant | Step-by-step merchant SDK integration (Express, Hono, or Next.js) | | integrate-agent | Agent SDK setup with spending policies and gas estimates | | debug-transaction | Transaction troubleshooting by hash/signature | | manage-paywalls | Paywall management — list, create, update, delete, or review configuration | | monitor-payments | Payment monitoring — overview, failure investigation, pending transaction analysis |

CLI Options

--api-key=KEY           PincerPay API key (or PINCERPAY_API_KEY env var)
--facilitator-url=URL   Custom facilitator URL (or PINCERPAY_FACILITATOR_URL)
--transport=stdio|http  Transport type (default: stdio)
--port=PORT             HTTP port (default: 3100, only with --transport=http)

API Key

Get your API key from pincerpay.com/dashboard/settings.

Developer tools (scaffolding, gas estimates, chain listing, config validation, health checks) work without an API key. Operations tools (transactions, paywalls, agents, webhooks, merchant profile) require one.

License

MIT