mcp-safrapay — Claude Code MCP server: what it does, how to install
Connects coding agents to Safrapay Brazilian payment infrastructure for Pix, boleto, card operations, and dispute tracking.
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-safrapayWhat mcp-safrapay 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.
What it helps with
- 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 for the agent
- 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.
How to install mcp-safrapay
Platform CLI
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-safrapayReplace <…> with your own values
Platform CLI
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-safrapayReplace <…> with your own values
Config file
{
"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
Config file
{
"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
Platform CLI
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-safrapayReplace <…> 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-safrapay
How to install mcp-safrapay in Claude Code?
Run `claude mcp add mcp-safrapay -e SAFRAPAY_CLIENT_ID=<SAFRAPAY_CLIENT_ID> -e SAFRAPAY_CLIENT_SECRET=<SAFRAPAY_CLIENT_SECRET> -e SAFRAPAY_MERCHANT_ID=<SAFRAPAY_MERCHANT_ID> -- npx -y @codespar/mcp-safrapay`.
What does mcp-safrapay do?
It gives AI assistants direct access to the Safrapay Aditum gateway, handling card payments, Pix, boletos, settlement reconciliation, and dispute reviews.
Why is a sandbox account required for validation?
The BCRYPT string concatenation for gateway login is not explicitly defined in public Aditum docs. You need a test merchant account to confirm the auth handshake.
