mcp-picpay — Claude Code MCP server: what it does, how to install
Connects AI agents to the PicPay Business API. It handles Pix QR generation, checkout orders, recurring subscriptions, and merchant fund transfers.
claude mcp add --env PICPAY_TOKEN=<PICPAY_TOKEN> --env PICPAY_SELLER_TOKEN=<PICPAY_SELLER_TOKEN> --env PICPAY_BASE_URL=<PICPAY_BASE_URL> --transport stdio picpay -- npx -y @codespar/mcp-picpayWhat mcp-picpay does
The server provides 20 tools covering the PicPay Checkout and Recurrency APIs. Your assistant can initiate payments, return checkout links, or generate Pix QR codes. It also checks wallet balances in BRL. For payouts, the server handles single or batch B2P transfers.
Authentication requires setting PICPAY_TOKEN and PICPAY_SELLER_TOKEN environment variables. The seller token lets you verify incoming webhooks with validate_notification. Because the package is at version 0.1.0-alpha.1, verify subscription and plan schemas against live endpoints before pushing to production.
What it helps with
- Generate Pix QR codes and checkout payment links
- Query payment status by reference ID or issue refunds
- Send batch B2P transfers to multiple PicPay accounts
- Configure subscription plans and enroll buyers
- Verify webhook payloads using the seller token
Example prompts for the agent
- Create a checkout payment for order
order-42and return the Pix QR code - Check the merchant wallet balance and list recent transactions for today
- Submit a batch B2P transfer to the recipient list using
create_batch_payment
How to install mcp-picpay
Platform CLI
claude mcp add --env PICPAY_TOKEN=<PICPAY_TOKEN> --env PICPAY_SELLER_TOKEN=<PICPAY_SELLER_TOKEN> --env PICPAY_BASE_URL=<PICPAY_BASE_URL> --transport stdio picpay -- npx -y @codespar/mcp-picpayReplace <…> with your own values
Platform CLI
codex mcp add picpay --env PICPAY_TOKEN=<PICPAY_TOKEN> --env PICPAY_SELLER_TOKEN=<PICPAY_SELLER_TOKEN> --env PICPAY_BASE_URL=<PICPAY_BASE_URL> -- npx -y @codespar/mcp-picpayReplace <…> with your own values
Config file
{
"mcpServers": {
"picpay": {
"command": "npx",
"args": [
"-y",
"@codespar/mcp-picpay"
],
"env": {
"PICPAY_TOKEN": "<PICPAY_TOKEN>",
"PICPAY_SELLER_TOKEN": "<PICPAY_SELLER_TOKEN>",
"PICPAY_BASE_URL": "<PICPAY_BASE_URL>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"picpay": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codespar/mcp-picpay"
],
"env": {
"PICPAY_TOKEN": "<PICPAY_TOKEN>",
"PICPAY_SELLER_TOKEN": "<PICPAY_SELLER_TOKEN>",
"PICPAY_BASE_URL": "<PICPAY_BASE_URL>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e PICPAY_TOKEN=<PICPAY_TOKEN> -e PICPAY_SELLER_TOKEN=<PICPAY_SELLER_TOKEN> -e PICPAY_BASE_URL=<PICPAY_BASE_URL> picpay npx -y @codespar/mcp-picpayReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-picpay
How to install mcp-picpay in Claude Code?
Run claude mcp add mcp-picpay -e PICPAY_TOKEN=<PICPAY_TOKEN> -e PICPAY_SELLER_TOKEN=<PICPAY_SELLER_TOKEN> -- npx -y @codespar/mcp-picpay. You can also configure PICPAY_BASE_URL if custom endpoints are needed.
What does mcp-picpay do?
It gives agents 20 tools to interact with PicPay Business APIs. You can create payments, process refunds, manage recurring plans, and execute payouts directly from your coding assistant.
Which environment variables are required?
You must pass PICPAY_TOKEN for API authentication and PICPAY_SELLER_TOKEN for webhook validation. PICPAY_BASE_URL is optional and defaults to the public ecommerce endpoint.
