mcp-rinne

@codespar/mcp-rinne

Rinne 向け MCP サーバー — ブラジルのカード決済、PIX、銀行業務、決済インフラを対象に、API 全体をカバーします

Rinne とは？

Rinne はブラジルの決済インフラ API です。B2B2B モデルで運用されており、Organization が任意の数の Merchants を管理します。各加盟店は KYC を通じてオンボーディングし、Affiliation を介して決済プロバイダー（Rinne 自体、Cappta、Celcoin など）に接続します。その後の処理はすべてそのアフィリエーションを通じて行われ、カードおよび PIX 取引、カード・オン・ファイル、3D Secure、キャッシュアウト／出金、台帳、料金設定が含まれます。

この MCP サーバーは、カード決済だけでなく、Rinne REST API 全体をラップします。AI エージェントは、サンドボックスまたは本番環境で、加盟店の管理、取引の実行、資金の移動、アクセス権の管理を行えます。

クイックスタート

Claude Desktop

~/.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

.cursor/mcp.json または .vscode/mcp.json に追加します：

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

ツール（62）

会社

ツール	用途
get_company	認証済みの会社を取得します（キーのスコープに応じて組織または加盟店）
update_company	認証済みの会社を更新します

加盟店

ツール	用途
create_merchant	組織の下に加盟店を作成します（KYC）
list_merchants	加盟店の一覧を取得します
get_merchant	ID で加盟店の詳細を取得します
update_merchant	加盟店を更新します

アフィリエーション

ツール	用途
create_affiliation	決済プロバイダー（Rinne、Cappta、Celcoin など）に加盟店アカウントを作成します
register_affiliation	既存のプロバイダー認証情報を使用して、ゲートウェイモードのアフィリエーションを登録します
list_affiliations	組織全体または特定の加盟店のアフィリエーション一覧を取得します
get_affiliation	特定のアフィリエーションを取得します

カード・オン・ファイル

ツール	用途
store_card	今後の取引で再利用できるようにカードを保存します
list_cards	保存済みカードの一覧を取得します
get_card	ID で保存済みカードを取得します
delete_card	保存済みカードを削除します

3D Secure

ツール	用途
create_3ds_session	取引に先立って 3DS 認証セッションを作成します

取引

ツール	用途
create_transaction	カード（生データ、保存済み、または Apple Pay／Google Pay）または PIX の取引を作成します
authenticate_transaction	認証待ちの取引について 3DS を完了します
get_transaction	返金を含む取引の詳細とステータスを取得します
list_transactions	組織全体または特定の加盟店の取引一覧を取得します
cancel_transaction	保留中の取引（未払いの bolepix など）をキャンセルします
refund_transaction	取引の全額または一部を返金します
cancel_refund	まだ決済されていない返金をキャンセルします
get_transaction_receipt	取引の領収書（base64 PDF）を取得します
simulate_pay_transaction	サンドボックス専用 — 取引を支払い済みにします

PIX（入金キー）

ツール	用途
create_pix_collection_key	加盟店が支払いの 受け取り に使用する PIX キーを作成します
list_pix_collection_keys	加盟店の PIX 入金キー一覧を取得します

台帳

ツール	用途
list_ledger_entries	認証済みの会社の台帳エントリー一覧を取得します
get_ledger_entry	1 件の台帳エントリーを取得します

銀行業務

ツール	目的
create_bank_account	外部銀行口座（出金先）を登録します
update_bank_account	銀行口座をメイン口座に設定します
register_cashout_pix_key	外部PIXキーを出金先として登録します
get_balance	現在の残高を取得します
topup_balance	サンドボックスのみ — 残高への入金をシミュレートします
get_statement	指定した期間の加盟店の残高明細を取得します
create_internal_transfer	組織が保有する銀行口座間で資金を移動します
list_judicial_blockages	残高に影響する裁判所命令による口座凍結の一覧を取得します

出金

ツール	目的
create_cashout	銀行口座またはPIXキーへの出金を作成します
list_cashouts	出金の一覧を取得します
get_cashout	個別の出金を取得します
get_cashout_receipt	出金の領収書を取得します

料金設定

ツール	目的
list_fee_policies	料金ポリシー（加盟店に請求する料金）の一覧を取得します
create_fee_policy	料金ポリシーを作成します
replace_fee_policy	料金ポリシーを全体的に置き換えます
update_fee_policy	料金ポリシーを部分的に更新します
list_cost_policies	コストポリシー（プロバイダーから請求される料金）の一覧を取得します
list_mccs	加盟店カテゴリコードの一覧を取得します

Webhook

ツール	目的
get_webhook_dashboard_url	Webhookのエンドポイント／イベントを設定するURLを取得します

システム

ツール	目的
get_health	APIの稼働状況を確認します

アクセス管理 — JWTが必要

ツール	目的
create_api_key	APIキーを作成します（表示は一度のみ）
list_api_keys	APIキーの一覧を取得します（プレフィックスと末尾4文字のみ）
revoke_api_key	APIキーを取り消します
create_role	カスタムロールを作成します
list_roles	ロールの一覧を取得します
list_permissions	利用可能なすべての権限を取得します
get_current_session	JWTセッションのユーザー情報を取得します

ユーザー

ツール	目的
create_user	ユーザーを作成します（加盟店スコープ：x-api-key、組織スコープ：JWT）
list_users	ユーザーの一覧を取得します
update_user	ユーザーの名前／ロールを更新します — JWT、組織のみ
suspend_user	ユーザーを一時停止します — JWT、組織のみ
activate_user	ユーザーを再有効化します — JWT、組織のみ

郵便番号 — JWTが必要

ツール	目的
lookup_zipcode	CEPを使ってブラジルの住所を検索します

サンドボックス

ツール	目的
get_sandbox_guide	テストカード、金額に基づく取引拒否ルール、およびJWTが必要なツールを返します

カードデータは平文で送信されません

Rinneは、このAPI経由で生のカード番号やCVVを受け付けません。すべてのnumber／cvvフィールド（およびApple Pay／Google Payの場合はnetwork_token／cryptogram）には、ブラウザー上で動作するrinne-js Card/Wallet Elementが生成した暗号化トークン（"ev:..."）を指定する必要があります。生のPAN／CVVは400 VALIDATION_ERRORで拒否され、サーバー側で暗号化する方法はありません。

実際には、このサーバーはチェックアウト処理の後半を担います。rinne-jsのフロー（rinne-jsのドキュメントを参照）を実行してクライアント側でカード情報を収集・暗号化し、生成されたトークンをここでstore_cardまたはcreate_transactionに渡して処理を完了します。または、store_cardで保存済みのカードに課金する場合は、create_transactionでcard_idを使用します。

組織スコープと加盟店スコープ

トランザクション、カード、3DSセッション、アフィリエーション、銀行業務を扱うすべてのリソースでは、オプションのmerchant_idを指定できます。

• 省略 — 組織／自身のレベルで処理します。
• 指定 — 複数の加盟店を管理する組織の場合、指定した加盟店（/v1/merchants/{merchant_id}/...）を対象に処理します。

refund_transaction、get_statement、create_pix_collection_key／list_pix_collection_keysでは、常にmerchant_idが必要です。これらは加盟店レベルでのみ利用できます。

2 つの PIX キーリソース — 混同しないでください

Rinne には、名前の似たエンドポイントを持つ、異なる 2 つの PIX キーリソースがあります。

• create_pix_collection_key（/v1/merchants/{id}/pix/keys）— 加盟店が PIX 決済を受け取るために使用するキーで、プロバイダーとの提携情報（provider、key_type）に紐付けられます。
• register_cashout_pix_key（/v1/merchants/{id}/pix-keys または /v1/companies/me/pix-keys）— キャッシュアウトの出金先として登録する外部キー（key、primary）です。

認証

API の大半では x-api-key を使用しますが、Rinne のアクセス管理機能では意図的にこれを拒否します。API キーが漏えいしても、他のキー、ロール、ユーザーを作成できないようにするためです。これらのツールには、代わりに JWT セッションが必要です。

認証	使用するツール
x-api-key（RINNE_API_KEY）	その他すべて — 加盟店、提携、カード、3DS、トランザクション、PIX、銀行業務、キャッシュアウト、料金、Webhook、加盟店スコープのユーザー
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、および組織スコープの create_user／list_users／update_user／suspend_user／activate_user

このサーバーは、JWT が必要なツールの初回呼び出し時に遅延ログインし、トークンをキャッシュします。また、401 が発生した場合は一度だけ再ログインします。RINNE_COMPANY_ID が設定されている場合、複数の会社へのアクセス権を持つアカウントでは、ログイン直後にその会社を選択します。RINNE_EMAIL／RINNE_PASSWORD が設定されていない場合、JWT が必要なツールは、何も通知せずに失敗するのではなく、明確なエラーを返します。それ以外のサーバー機能は問題なく使用できます。

サンドボックス／テスト

デフォルトではサンドボックス（https://api-sandbox.rinne.com.br/core）を使用します。本番環境（https://api.rinne.com.br/core）を使用するには、RINNE_SANDBOX=false を設定します。

サンドボックスのシミュレーションルール

完全な JSON は get_sandbox_guide を呼び出して確認するか、以下を参照してください。

テストカード

カード番号	ブランド	3DS
5155901222280001	Mastercard	なし
4012001037141112	Visa	なし
4242424242424242	Visa	チャレンジ

金額ごとの結果

結果はカード番号ではなく、**金額の下 2 桁（セント単位）**によって決まります。

下 2 桁	結果
00	承認
51	拒否 — 残高不足
05	拒否 — 承認不可
54	拒否 — カードの有効期限切れ

例：amount: 1051 → コード 51 で REFUSED。

PIX

WAITING_PAYMENT 状態の PIX トランザクションを支払い済みにするには、simulate_pay_transaction を使用します（サンドボックスのみ）。

参照：Rinne テストガイド

環境変数

変数	必須	説明
RINNE_API_KEY	はい	API キー。x-api-key として送信されます
RINNE_SANDBOX	いいえ	デフォルトではサンドボックスを使用します。本番環境では "false" を設定します
RINNE_EMAIL	いいえ	JWT が必要なツールで使用するログイン識別子
RINNE_PASSWORD	いいえ	ログインパスワード。RINNE_EMAIL と組み合わせて使用します
RINNE_COMPANY_ID	いいえ	複数会社のアカウントで、ログイン後に選択する会社

リンク

• Rinne ドキュメント
• rinne-js SDK
• MCP Dev LATAM
• ランディングページ

エンタープライズ

エージェントによる決済にガバナンス、予算上限、監査証跡が必要ですか？CodeSpar Enterprise は、これらの MCP サーバーにポリシーエンジン、決済ルーティング、コンプライアンステンプレートを追加します。

ライセンス

MIT