mcp-pagbrasil — Claude Code MCP server: Brazil payments
Wires three PagBrasil tools into your agent: create an order, check its status, issue a refund. Useful when your store sells into Brazil and takes Pix or boleto.
claude mcp add --env PAGBRASIL_PBTOKEN=<PAGBRASIL_PBTOKEN> --env PAGBRASIL_SECRET=<PAGBRASIL_SECRET> --env PAGBRASIL_BASE_URL=<PAGBRASIL_BASE_URL> --transport stdio pagbrasil -- npx -y @codespar/mcp-pagbrasilWhat mcp-pagbrasil does
The server talks to PagBrasil, an acquirer that handles cross-border sales into Brazil. You get three tools. create_order opens an order or payment request (pix, boleto, creditcard); get_order returns where that order stands now; refund_order sends money back on a settled payment. Pix replies include pix_code and pix_image, boleto replies the bar code plus a PDF link.
The transport is unusual. PagBrasil wants form-urlencoded input and answers in XML, so the server hands the raw XML back to the agent under xml and nothing gets dropped on the way. Merchant token and secret phrase ride in the request body, not in an auth header; the server fills them from PAGBRASIL_PBTOKEN and PAGBRASIL_SECRET. Both are required and both come from the PagBrasil dashboard.
A valid customer_taxid is mandatory — a real CPF or CNPJ. The agent has to ask for it, inventing one breaks the request. order_number stays unique per taxpayer: repeat it with the same taxid and the call is an idempotent no-op, change the taxid and you get Duplicated order. Amounts go in amount_brl as a string in major units, so '125.00' means R$ 125,00. Requests hit https://sandbox.pagbrasil.com/api by default; production hosts are issued per merchant once the Payment Service Agreement is signed, and you point PAGBRASIL_BASE_URL at yours.
What it helps with
- charge a Brazilian buyer with Pix and show the QR code
- issue a boleto and hand over the bar code and PDF
- poll an order until the payment settles
- refund a settled order in part or in full
- take a local card payment with installments
Example prompts for the agent
- Create an order for 249.90 for the CPF I'm about to paste and give me the Pix code.
- Check order 1042 — has the payment landed yet?
- Refund 50.00 on order 1042, partial amount.
How to install mcp-pagbrasil
Platform CLI
claude mcp add --env PAGBRASIL_PBTOKEN=<PAGBRASIL_PBTOKEN> --env PAGBRASIL_SECRET=<PAGBRASIL_SECRET> --env PAGBRASIL_BASE_URL=<PAGBRASIL_BASE_URL> --transport stdio pagbrasil -- npx -y @codespar/mcp-pagbrasilReplace <…> with your own values
Platform CLI
codex mcp add pagbrasil --env PAGBRASIL_PBTOKEN=<PAGBRASIL_PBTOKEN> --env PAGBRASIL_SECRET=<PAGBRASIL_SECRET> --env PAGBRASIL_BASE_URL=<PAGBRASIL_BASE_URL> -- npx -y @codespar/mcp-pagbrasilReplace <…> with your own values
Config file
{
"mcpServers": {
"pagbrasil": {
"command": "npx",
"args": [
"-y",
"@codespar/mcp-pagbrasil"
],
"env": {
"PAGBRASIL_PBTOKEN": "<PAGBRASIL_PBTOKEN>",
"PAGBRASIL_SECRET": "<PAGBRASIL_SECRET>",
"PAGBRASIL_BASE_URL": "<PAGBRASIL_BASE_URL>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"pagbrasil": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codespar/mcp-pagbrasil"
],
"env": {
"PAGBRASIL_PBTOKEN": "<PAGBRASIL_PBTOKEN>",
"PAGBRASIL_SECRET": "<PAGBRASIL_SECRET>",
"PAGBRASIL_BASE_URL": "<PAGBRASIL_BASE_URL>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e PAGBRASIL_PBTOKEN=<PAGBRASIL_PBTOKEN> -e PAGBRASIL_SECRET=<PAGBRASIL_SECRET> -e PAGBRASIL_BASE_URL=<PAGBRASIL_BASE_URL> pagbrasil npx -y @codespar/mcp-pagbrasilReplace <…> 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-pagbrasil
How do I install mcp-pagbrasil in Claude Code?
Run claude mcp add mcp-pagbrasil -e PAGBRASIL_PBTOKEN=<PAGBRASIL_PBTOKEN> -e PAGBRASIL_SECRET=<PAGBRASIL_SECRET> -- npx -y @codespar/mcp-pagbrasil. A second variant with --env and --transport stdio lets you pass PAGBRASIL_BASE_URL as well.
What does mcp-pagbrasil do?
It creates PagBrasil payment orders, reads their status and processes refunds. The API answers in XML and the agent gets that XML as-is.
Is PagBrasil the same as PagBank or PagSeguro?
No, it's a separate acquirer built for international merchants selling into Brazil. It covers Pix, Boleto Flash, PEC Flash and local cards with installments, and this server speaks its API only.
