@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

| Tool | Purpose | |---|---| | get_company | Get the authenticated company (org or merchant, depending on key scope) | | update_company | Update the authenticated company |

Merchants

| Tool | Purpose | |---|---| | create_merchant | Create a merchant under your organization (KYC) | | list_merchants | List merchants | | get_merchant | Get merchant details by ID | | update_merchant | Update a merchant |

Affiliations

| Tool | Purpose | |---|---| | create_affiliation | Create a merchant account with a payment provider (Rinne, Cappta, Celcoin, ...) | | register_affiliation | Register a gateway-mode affiliation using existing provider credentials | | list_affiliations | List affiliations, org-wide or for one merchant | | get_affiliation | Get a specific affiliation |

Cards on file

| Tool | Purpose | |---|---| | store_card | Save a card for reuse in future transactions | | list_cards | List stored cards | | get_card | Get a stored card by ID | | delete_card | Delete a stored card |

3D Secure

| Tool | Purpose | |---|---| | create_3ds_session | Create a 3DS authentication session ahead of a transaction |

Transactions

| Tool | Purpose | |---|---| | create_transaction | Create a card (raw, stored, or Apple Pay/Google Pay) or PIX transaction | | authenticate_transaction | Complete 3DS for a transaction awaiting authentication | | get_transaction | Get transaction details and status, including refunds | | list_transactions | List transactions, org-wide or for one merchant | | cancel_transaction | Cancel a pending transaction (e.g. unpaid bolepix) | | refund_transaction | Refund a transaction, fully or partially | | cancel_refund | Cancel a refund that hasn't settled yet | | get_transaction_receipt | Get a transaction's receipt (base64 PDF) | | simulate_pay_transaction | Sandbox only — mark a transaction as paid |

PIX (collection keys)

| Tool | Purpose | |---|---| | create_pix_collection_key | Create a PIX key the merchant uses to receive payments | | list_pix_collection_keys | List the merchant's PIX collection keys |

Ledger

| Tool | Purpose | |---|---| | list_ledger_entries | List ledger entries for the authenticated company | | get_ledger_entry | Get a single ledger entry |

Banking

| Tool | Purpose | |---|---| | create_bank_account | Register an external bank account (payout destination) | | update_bank_account | Set a bank account as primary | | register_cashout_pix_key | Register an external PIX key as a payout destination | | get_balance | Get the current balance | | topup_balance | Sandbox only — simulate funding the balance | | get_statement | Get a merchant's balance statement for a date range | | create_internal_transfer | Transfer funds between your org's own bank accounts | | list_judicial_blockages | List court-ordered account freezes affecting balances |

Cashouts

| Tool | Purpose | |---|---| | create_cashout | Create a payout to a bank account or PIX key | | list_cashouts | List cashouts | | get_cashout | Get a single cashout | | get_cashout_receipt | Get a cashout's receipt |

Pricing

| Tool | Purpose | |---|---| | list_fee_policies | List fee policies (what you charge merchants) | | create_fee_policy | Create a fee policy | | replace_fee_policy | Replace a fee policy in full | | update_fee_policy | Partially update a fee policy | | list_cost_policies | List cost policies (what providers charge you) | | list_mccs | List Merchant Category Codes |

Webhooks

| Tool | Purpose | |---|---| | get_webhook_dashboard_url | Get the URL to configure webhook endpoints/events |

System

| Tool | Purpose | |---|---| | get_health | Check API health status |

Access management — JWT required

| Tool | Purpose | |---|---| | create_api_key | Create an API key (shown once) | | list_api_keys | List API keys (prefix + last 4 only) | | revoke_api_key | Revoke an API key | | create_role | Create a custom role | | list_roles | List roles | | list_permissions | List all available permissions | | get_current_session | Whoami for the JWT session |

Users

| Tool | Purpose | |---|---| | create_user | Create a user (merchant scope: x-api-key; org scope: JWT) | | list_users | List users | | update_user | Update a user's name/roles — JWT, org only | | suspend_user | Suspend a user — JWT, org only | | activate_user | Reactivate a user — JWT, org only |

Zipcode — JWT required

| Tool | Purpose | |---|---| | lookup_zipcode | Look up a Brazilian address by CEP |

Sandbox

| Tool | Purpose | |---|---| | get_sandbox_guide | Return test cards, the amount-based decline rule, and which tools need JWT |

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:

| Auth | Used by | |---|---| | x-api-key (RINNE_API_KEY) | Everything else — merchants, affiliations, cards, 3DS, transactions, PIX, banking, cashouts, pricing, webhooks, merchant-scoped users | | JWT (RINNE_EMAIL + RINNE_PASSWORD) | create_api_key, list_api_keys, revoke_api_key, create_role, list_roles, list_permissions, get_current_session, lookup_zipcode, and org-scoped create_user/list_users/update_user/suspend_user/activate_user |

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

| Card number | Brand | 3DS | |---|---|---| | 5155901222280001 | Mastercard | No | | 4012001037141112 | Visa | No | | 4242424242424242 | Visa | Challenge |

Outcome by amount

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

| Last 2 digits | Result | |---|---| | 00 | Approved | | 51 | Refused — insufficient funds | | 05 | Refused — do not honor | | 54 | Refused — expired card |

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

| Variable | Required | Description | |----------|----------|-------------| | RINNE_API_KEY | Yes | API key, sent as x-api-key | | RINNE_SANDBOX | No | Defaults to sandbox; set to "false" for production | | RINNE_EMAIL | No | Login identifier for JWT-gated tools | | RINNE_PASSWORD | No | Login password, paired with RINNE_EMAIL | | RINNE_COMPANY_ID | No | Company to select after login, for multi-company accounts |

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