# mcp-safrapay

Connects coding agents to Safrapay Brazilian payment infrastructure for Pix, boleto, card operations, and dispute tracking.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 274
- Author: codespar
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/codespar/mcp-dev-latam/tree/HEAD/packages/payments/safrapay
- Updated: 2026-09-27
- HTML: https://affpapa.org/en/nevibecode/mcp/mcp-safrapay

## What it does

This MCP server exposes Banco Safra's acquirer endpoints on the Aditum engine to LLMs. It packs 22 tools covering credit charges, Pix generation, recurring subscriptions, and hosted payment links. Agents can query installment plans, inspect chargeback dispute deadlines, and manage webhook registrations directly in the conversation.

Safrapay routes traffic across four separate environments: gateway, portal, reconciliation, and webhook servers. Authentication relies on an initial CNPJ and MerchantToken exchange hashed via BCRYPT, which issues a temporary JWT. Because public Aditum documentation leaves the exact input string format ambiguous, verify the handshake against a real sandbox merchant account before running live transactions.

The server runs over stdio via `npx` or as an HTTP daemon. Configuration requires `SAFRAPAY_CLIENT_ID`, `SAFRAPAY_CLIENT_SECRET`, and `SAFRAPAY_MERCHANT_ID` passed as environment variables.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `SAFRAPAY_CLIENT_ID`, `SAFRAPAY_CLIENT_SECRET`, `SAFRAPAY_MERCHANT_ID`, `SAFRAPAY_ENV` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env SAFRAPAY_CLIENT_ID=<SAFRAPAY_CLIENT_ID> --env SAFRAPAY_CLIENT_SECRET=<SAFRAPAY_CLIENT_SECRET> --env SAFRAPAY_MERCHANT_ID=<SAFRAPAY_MERCHANT_ID> --env SAFRAPAY_ENV=<SAFRAPAY_ENV> --transport stdio safrapay -- npx -y @codespar/mcp-safrapay
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add safrapay --env SAFRAPAY_CLIENT_ID=<SAFRAPAY_CLIENT_ID> --env SAFRAPAY_CLIENT_SECRET=<SAFRAPAY_CLIENT_SECRET> --env SAFRAPAY_MERCHANT_ID=<SAFRAPAY_MERCHANT_ID> --env SAFRAPAY_ENV=<SAFRAPAY_ENV> -- npx -y @codespar/mcp-safrapay
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "safrapay": {
            "command": "npx",
            "args": [
                "-y",
                "@codespar/mcp-safrapay"
            ],
            "env": {
                "SAFRAPAY_CLIENT_ID": "<SAFRAPAY_CLIENT_ID>",
                "SAFRAPAY_CLIENT_SECRET": "<SAFRAPAY_CLIENT_SECRET>",
                "SAFRAPAY_MERCHANT_ID": "<SAFRAPAY_MERCHANT_ID>",
                "SAFRAPAY_ENV": "<SAFRAPAY_ENV>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "safrapay": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@codespar/mcp-safrapay"
            ],
            "env": {
                "SAFRAPAY_CLIENT_ID": "<SAFRAPAY_CLIENT_ID>",
                "SAFRAPAY_CLIENT_SECRET": "<SAFRAPAY_CLIENT_SECRET>",
                "SAFRAPAY_MERCHANT_ID": "<SAFRAPAY_MERCHANT_ID>",
                "SAFRAPAY_ENV": "<SAFRAPAY_ENV>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e SAFRAPAY_CLIENT_ID=<SAFRAPAY_CLIENT_ID> -e SAFRAPAY_CLIENT_SECRET=<SAFRAPAY_CLIENT_SECRET> -e SAFRAPAY_MERCHANT_ID=<SAFRAPAY_MERCHANT_ID> -e SAFRAPAY_ENV=<SAFRAPAY_ENV> safrapay npx -y @codespar/mcp-safrapay
```
Replace <…> with your own values

## When to use it
- issue Pix charges and generate boleto slips
- tokenize credit cards and initiate 3DS authentication
- configure payment splits across merchant accounts
- pull settlement reconciliation files and inspect chargebacks

## Example prompts
- Create a Pix charge for order 4821 with an expiration of 30 minutes.
- Tokenize the card details for recurring billing using `tokenize_card`.
- Query dispute reasons and evidence deadlines for chargeback `ch_123`.

## Similar
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89408
- [CCXT](https://affpapa.org/en/nevibecode/mcp/ccxt.md) — MCP server · ★ 44583
- [Finance Toolkit](https://affpapa.org/en/nevibecode/mcp/finance-toolkit.md) — MCP server · ★ 5458
- [EdgarTools](https://affpapa.org/en/nevibecode/mcp/edgartools.md) — MCP server · ★ 2814
- [LetsFG — Flights & Hotels](https://affpapa.org/en/nevibecode/mcp/letsfg-flights-hotels.md) — MCP server · ★ 2188
- [AutoTS](https://affpapa.org/en/nevibecode/mcp/autots.md) — MCP server · ★ 1434

From the same set: [codespar/mcp-dev-latam](https://affpapa.org/en/nevibecode/by/codespar/mcp-dev-latam.md) — 124 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md