mcpField
M
mcp-pagbrasil

mcp-pagbrasil

Local
github.com/codesparFinance275Updated 4w ago
Repository

About mcp-pagbrasil

mcp-pagbrasil is an MCP server for PagBrasil, a cross-border acquirer for international merchants selling into Brazil. It lets agents create orders, check status and issue refunds, and is distinct from PagBank and PagSeguro.

Key features

  1. 01Create orders and request payments
  2. 02Supports Pix, Boleto Flash, PEC Flash and installment credit cards
  3. 03Fetch order status to confirm settlement
  4. 04Partial or full refunds by amount
  5. 05Returns raw XML responses to the agent

Use cases

  1. 01Generate Pix payment codes or Boleto bills for Brazilian buyers
  2. 02Poll order status to detect when a payment settles
  3. 03Handle partial or full refunds from an agent workflow

MCP support

The server exposes three MCP tools, create_order, get_order and refund_order, which map to PagBrasil's order creation, lookup and refund endpoints.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "codespar-mcp-pagbrasil": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-pagbrasil"
      ],
      "env": {
        "PAGBRASIL_PBTOKEN": "<PAGBRASIL_PBTOKEN>",
        "PAGBRASIL_SECRET": "<PAGBRASIL_SECRET>",
        "PAGBRASIL_BASE_URL": "<PAGBRASIL_BASE_URL>"
      }
    }
  }
}
Run commandnpx -y @codespar/mcp-pagbrasil
Environment variables to set
PAGBRASIL_PBTOKENSecretMerchant token (pbtoken) from the PagBrasil Dashboard
PAGBRASIL_SECRETSecretSecret phrase from the PagBrasil Dashboard
PAGBRASIL_BASE_URLAPI base URL. Defaults to https://sandbox.pagbrasil.com/api; production hosts are issued per-merchant.

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npm@codespar/mcp-pagbrasil0.1.0

Tools

3

Saved tool list · updated 2w ago

ParameterTypeRequiredDescription
amount_brlstringYesAmount in Brazilian Real, major units as a string (e.g. '125.00')
address_zipstringNoBuyer CEP
address_citystringNoBuyer city
order_numberstringYesUnique order reference per customer_taxid (idempotency anchor)
payment_typeenumYesPayment methodpix | boleto | creditcard
product_namestringNoProduct / charge description
address_statestringNoBuyer state (UF)
customer_namestringYesBuyer full name
address_streetstringNoBuyer street address
customer_emailstringNoBuyer email
customer_phonestringNoBuyer phone
customer_taxidstringYesBuyer CPF (individuals) or CNPJ (companies) — must be a valid Brazilian tax id

Details

From the project README

@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.

npm License: MIT

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)

ToolEndpointWhat it does
create_orderPOST /order/addCreate an order / request a payment (pix, boleto, creditcard). Pix responses carry pix_code + pix_image; boleto responses carry the bar code + PDF URL
get_orderPOST /order/getFetch an order's current status — poll to detect settlement
refund_orderPOST /order/refundRefund a settled order (amount_brl for partial, omit for full)

Environment

VariableRequiredDescription
PAGBRASIL_PBTOKENyesMerchant token from the PagBrasil Dashboard
PAGBRASIL_SECRETyesSecret phrase from the Dashboard
PAGBRASIL_BASE_URLnoDefaults 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

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.