MCP Rinne

@codespar/mcp-rinne

MCP server for Rinne — Brazilian card acquiring, PIX, banking, and payment infrastructure, covering the full API surface

What is Rinne?

Rinne is a Brazilian payment infrastructure API. It runs a B2B2B model: your Organization manages any number of Merchants, each merchant onboards via KYC and connects to a payment provider (Rinne itself, Cappta, Celcoin, ...) through an Affiliation, and everything downstream flows through that affiliation — card and PIX transactions, cards-on-file, 3D Secure, cashouts/payouts, ledger, and pricing.

This MCP server wraps the entire Rinne REST API — not just card acquiring — so AI agents can manage merchants, run transactions, move money, and administer access in sandbox or production.

Quick Start

Claude Desktop

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

{

"mcpServers": { "rinne": { "command": "npx", "args": ["-y", "@codespar/mcp-rinne"], "env": { "RINNE_API_KEY": "your-api-key", "RINNE_SANDBOX": "true" } } } }

Claude Code

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

Cursor / VS Code

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

{

"servers": { "rinne": { "command": "npx", "args": ["-y", "@codespar/mcp-rinne"], "env": { "RINNE_API_KEY": "your-api-key", "RINNE_SANDBOX": "true" } } } }

Tools (62)

Company

Merchants

Affiliations

Cards on file

3D Secure

Transactions

PIX (collection keys)

Ledger

Banking

Cashouts

Pricing

Webhooks

System

Access management — JWT required

Users

Zipcode — JWT required

Sandbox

Card data is never sent in the clear

Rinne does not accept a raw card number or CVV over this API. Every number/cvv field (and, for Apple Pay/Google Pay, network_token/cryptogram) must already be an encrypted token ("ev:...") produced by the rinne-js Card/Wallet Element running in a browser — a raw PAN/CVV is rejected with 400 VALIDATION_ERROR, and there is no server-side encryption path.

In practice, this server is the second half of a checkout: run a rinne-js flow (see rinne-js docs) to collect and encrypt the card client-side, then hand the resulting token to store_card or create_transaction here to finish the operation. Alternatively, use card_id on create_transaction to charge a card already saved via store_card.

Organization vs. merchant scope

Every resource that operates on transactions, cards, 3DS sessions, affiliations, or banking accepts an optional merchant_id:

• Omitted — acts at the organization/self level.
• Provided — acts on that specific merchant (/v1/merchants/{merchant_id}/...), for an organization managing multiple merchants.

refund_transaction, get_statement, and create_pix_collection_key/list_pix_collection_keys always require merchant_id — they only exist at the merchant level.

Two PIX key resources — don't confuse them

Rinne has two distinct PIX-key resources with similarly-named endpoints:

• `create_pix_collection_key` (/v1/merchants/{id}/pix/keys) — a key the merchant uses to *receive* PIX payments, tied to a provider affiliation (provider, key_type).
• `register_cashout_pix_key` (/v1/merchants/{id}/pix-keys or /v1/companies/me/pix-keys) — an *external* key registered as a *payout* destination for cashouts (key, primary).

Authentication

Most of the API uses x-api-key, but Rinne's access-management surface deliberately rejects it — a leaked API key must not be able to create other keys, roles, or users. Those tools need a JWT session instead:

This server logs in lazily on the first JWT-gated tool call and caches the token, re-logging-in once on a 401. If RINNE_COMPANY_ID is set, it selects that company right after login (for accounts with access to multiple companies). If RINNE_EMAIL/RINNE_PASSWORD aren't set, JWT-gated tools return a clear error instead of failing silently — the rest of the server works fine without them.

Sandbox / Testing

Defaults to sandbox (https://api-sandbox.rinne.com.br/core). Set RINNE_SANDBOX=false for production (https://api.rinne.com.br/core).

Sandbox simulation rules

Call get_sandbox_guide for the full JSON, or see below:

Test cards

Outcome by amount

The last two digits of the amount (in cents) determine the result — not the card number:

Example: amount: 1051 → REFUSED with code 51.

PIX

Use simulate_pay_transaction (sandbox only) to mark a WAITING_PAYMENT PIX transaction as paid.

Reference: Rinne testing guide

Environment Variables

Links

• Rinne Documentation
• rinne-js SDK
• MCP Dev LATAM
• Landing Page

Enterprise

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

License

MIT