MCP server

npm payzu-mcp-pix GitHub repo SKILL.md (lightweight alternative)

MCP is the open protocol that lets AI assistants call external tools via JSON-RPC. payzu-mcp-pix exposes 29 curated tools from the Pix Processamento API, with readable names (pix.create, account.balance, etc), type validation and consistent error handling.

When to use MCP vs SKILL.md vs SDK

Scenario	Use
AI executes real calls on your PayZu account (create Pix, check balance, etc)	MCP
AI generates code that you paste into your app	SKILL.md
Your production app talks to PayZu	SDK (`npm install payzu-pix`)

Installation

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "payzu-pix": {
      "command": "npx",
      "args": ["-y", "payzu-mcp-pix"],
      "env": {
        "PAYZU_TOKEN": "<your-token-from-dashboard>"
      }
    }
  }
}

Restart Claude Desktop. Test by asking "what's my PayZu balance?", Claude will call account.balance on its own.

Cursor

.cursor/mcp.json in the project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "payzu-pix": {
      "command": "npx",
      "args": ["-y", "payzu-mcp-pix"],
      "env": { "PAYZU_TOKEN": "..." }
    }
  }
}

Continue, Codeium, others

Same config (all follow the MCP standard). See the package README for details.

Configuration

Env var	Required	Default	Description
`PAYZU_TOKEN`	yes	,	Bearer token from abrirconta.payzu.com.br
`PAYZU_API_URL`	no	`https://api.payzu.processamento.com/v1`	Override for whitelabel

Tool list (29)

All names in snake_case with namespace per domain. Each tool has a description with a direct link to the endpoint page in the docs.

Pix charges (4)

Tool	HTTP
`pix.create`	`POST /pix`
`pix.get`	`GET /pix`
`pix.qr_code`	`GET /pix/qr-code/{id}`
`pix.proof`	`GET /proof/{id}`

Withdrawals (6)

Tool	HTTP
`withdraw.create`	`POST /withdraw`
`withdraw.get`	`GET /withdraw`
`withdraw.by_qr`	`POST /withdraw/qrcode`
`withdraw.read_qr`	`POST /pix/qrcode/read`
`withdraw.dict`	`GET /pix-key/{key}`
`withdraw.proof`	`GET /withdraw/proof/{id}`

Internal transfer (2)

Tool	HTTP
`internal_transfer.create`	`POST /internal-transfer`
`internal_transfer.get`	`GET /internal-transfer`

Account (2)

Tool	HTTP
`account.profile`	`GET /user`
`account.balance`	`GET /user/balance`

Reports (6)

Tool	HTTP
`reports.list_transactions`	`GET /user/transactions`
`reports.get_transaction`	`GET /user/transactions/{id}`
`reports.create_csv`	`POST /user/report`
`reports.list_jobs`	`GET /user/reports`
`reports.get_job`	`GET /user/report/{id}`
`reports.download`	`GET /user/report/{id}/download`

Callbacks (4)

Tool	HTTP
`callbacks.list`	`GET /user/callbacks`
`callbacks.get`	`GET /user/callback/{id}`
`callbacks.resend`	`POST /user/callback/{id}/resend`
`callbacks.resend_bulk`	`POST /user/callbacks/resend`

MED infractions (5)

Tool	HTTP
`infractions.list`	`GET /infractions`
`infractions.get`	`GET /infractions/{id}`
`infractions.create_defense`	`POST /infractions/{id}/defense`
`infractions.list_defenses`	`GET /infractions/{id}/defenses`
`infractions.get_defense`	`GET /infractions/{id}/defense/{defenseId}`

Applied conventions

Values in decimal BRL, tool rejects cents (9990 becomes a validation error; it has to be 99.90).
clientReference required on creations (idempotência).
callbackUrl required on creations (without it nobody tells you the status).
Auto-retry on 5xx/429 with exponential backoff + jitter (max 3 attempts).
Errors include requestId, copy and paste to support if needed.
Zero admin endpoints, only public/client surface.

Usage example (Claude Desktop)

After configuring, conversations like:

"Create a PayZu charge for R$ 50 with reference order-abc"

Claude will pick pix.create, validate the arguments and call the API. Shows you the id, qrCodeText and qrCodeUrl in the chat.

"How much balance do I have?"

Claude calls account.balance and responds with the number.

"List the last 10 canceled transactions"

Claude calls reports.list_transactions with status: CANCELED, limit: 10.

Support

Report bug Full docs PayZu support

MCP server

On this page