io.github.codespar/mcp-pagbrasil

io.github.codespar/mcp-pagbrasil · 273 stars · TypeScript · MIT

MCP server PagBrasil — cross-border acquiring into Brazil: Pix, Boleto Flash, refunds

Install

The repo has no one-line install. Follow its README.

Published as

npm@codespar/mcp-pagbrasilstdio

From the server's entry in the official MCP Registry.

Open the repo

Configuration

Name	Set as	What it is
`PAGBRASIL_PBTOKEN`Required · Secret	Env var	Merchant token (pbtoken) from the PagBrasil Dashboard
`PAGBRASIL_SECRET`Required · Secret	Env var	Secret phrase from the PagBrasil Dashboard
`PAGBRASIL_BASE_URL`Optional	Env var	API base URL. Defaults to https://sandbox.pagbrasil.com/api; production hosts are issued per-merchant.

Files

packages/payments/pagbrasil/README.md

@codespar/mcp-pagbrasil

MCP server for PagBrasil — the cross-border acquirer for international merchants selling into Brazil: Pix, Automatic Pix (PagStream), Boleto Flash, PEC Flash and local credit cards with installments. Distinct from PagBank/PagSeguro.

Quick Start

Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pagbrasil": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-pagbrasil"],
      "env": {
        "PAGBRASIL_PBTOKEN": "your-merchant-token",
        "PAGBRASIL_SECRET": "your-secret-phrase"
      }
    }
  }
}

Claude Code

claude mcp add pagbrasil -- npx @codespar/mcp-pagbrasil

Cursor / VS Code

Add to .cursor/mcp.json or .vscode/mcp.json:

{
  "servers": {
    "pagbrasil": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-pagbrasil"],
      "env": {
        "PAGBRASIL_PBTOKEN": "your-merchant-token",
        "PAGBRASIL_SECRET": "your-secret-phrase"
      }
    }
  }
}

Authentication

Every request carries the merchant token (pbtoken) and the secret phrase as body fields — there is no auth header. This server injects both from PAGBRASIL_PBTOKEN and PAGBRASIL_SECRET.

API shape (worth knowing)

PagBrasil's API is form-urlencoded (not JSON) and answers XML. The merchant token (pbtoken) and secret phrase travel as body fields on every request — this server injects both from the environment. Tool responses hand the raw XML to the agent under xml so no fields are lost.

Tools (3)

Tool	Endpoint	What it does
`create_order`	`POST /order/add`	Create an order / request a payment (pix, boleto, creditcard). Pix responses carry `pix_code` + `pix_image`; boleto responses carry the bar code + PDF URL
`get_order`	`POST /order/get`	Fetch an order's current status — poll to detect settlement
`refund_order`	`POST /order/refund`	Refund a settled order (`amount_brl` for partial, omit for full)

Environment

Variable	Required	Description
`PAGBRASIL_PBTOKEN`	yes	Merchant token from the PagBrasil Dashboard
`PAGBRASIL_SECRET`	yes	Secret phrase from the Dashboard
`PAGBRASIL_BASE_URL`	no	Defaults to `https://sandbox.pagbrasil.com/api`. Production hosts are issued per-merchant after the Payment Service Agreement — set the URL your dashboard provides

Notes

amount_brl is in major units as a string: '125.00' = R$ 125,00.
order_number must be unique per customer_taxid. Same number + same taxid = idempotent no-op; same number + different taxid = rejected (Duplicated order).
customer_taxid must be a valid CPF or CNPJ — agents should ask the user, never invent one.

Enterprise

Need governance, budget limits, and audit trails for agent-driven payments on PagBrasil? CodeSpar Enterprise adds a policy engine, payment routing, and compliance templates on top of these MCP servers.

License

MIT © CodeSpar

Facts

Kind: MCP server
Repo: codespar/mcp-dev-latam
Group: Uncategorized
Stars: 273
License: MIT
Language: TypeScript
Last push: 2026-09-27
Forks: 50
MCP Registry: io.github.codespar/mcp-pagbrasil
Homepage: codespar.dev/servers
Topics: agentic-commerce, ai-agents, brazil, claude, fintech, latin-america, llm-tools, mcp, model-context-protocol, nfe, open-finance, payments, pix