mcp-santander

@codespar/mcp-santander

Santander Brasil 向け MCP サーバーです。ブラジルで3番目に大きい民間銀行です。

ブラジルの民間銀行トップ3を完成させる構成です：Itaú + Bradesco + Santander。同業他社と同じ OAuth2 + mTLS の形式ですが、加盟店向けの契約は異なります。

Pix、boleto、キャッシュマネジメントを相当量取り扱う加盟店は、PSP を介さず Santander と直接連携します。

ステータス：アルファ版（0.1.0-alpha.1）

Santander の Developer Portal は契約が必要です。Pix、Cobrança、Arrecadação、Extrato の完全な OpenAPI 仕様は、オンボーディング済みの加盟店のみ閲覧できます。以下の項目は、Santander の公開統合ガイドで確認済みです。

• 本番ホスト：https://trust-open.api.santander.com.br
• サンドボックスホスト：https://trust-sandbox.api.santander.com.br
• OAuth2 トークン：/auth/oauth/v2/token
• Cobrança v2 のベースパス：/collection_bill_management/v2/workspaces/{workspace_id}/bank_slips

残りのパス（Pix、Arrecadação、Extrato）は、（a）BACEN Pix v2 の標準パス、（b）Santander の公開情報、（c）Itaú／Bradesco／BB で共通する規約に基づく最善の推定です。未確認のパスには、ソース内で TODO(verify) のフラグが付いています。

0.1.x の期間中は正確なバージョンに固定してください。オンボーディング済みの加盟店が検証できるようになったら、ポータルの仕様に合わせてパスを修正します。

ツール（23）

ツール	用途
get_oauth_token	Santander Developer Portal 用の OAuth2 client_credentials bearer トークンを発行するか、キャッシュ済みのトークンを返します。
send_pix	加盟店の Santander アカウントから Pix の送金を開始します。
create_pix_qr	QR コード付きの動的 Pix 請求（cob）を作成します。
get_pix	BCB endToEndId（E）を指定して Pix 取引を取得します。
resolve_dict_key	Pix 送信前に、DICT キー（CPF、CNPJ、メールアドレス、電話番号、EVP）から所有者のアカウント情報を取得します。
refund_pix	以前に受け取った Pix を返金（devolução）します。
create_boleto	Santander Cobrança（collection_bill_management v2）経由で boleto を発行します。
get_boleto	Santander の bill_id を指定して boleto を取得します（collection_bill_management v2 経由の SONDA クエリ）。
cancel_boleto	支払い前の未決済 boleto を取り消し（baixa）ます。
get_statement	指定した期間の口座明細の取引を取得します。
create_pix_cobv	支払期限付きの Pix 請求（cobv — cobrança com vencimento）を作成します。
get_pix_cob	txid を指定して Pix 即時請求（cob）を取得します。
list_pix_cob	指定した期間に作成された Pix 即時請求（cob）を一覧表示します。
update_pix_cob	既存の Pix 即時請求を更新（PATCH）します。
list_pix_received	指定した期間に受け取った Pix（Pix recebidos）を一覧表示します。
register_dict_key	加盟店の Santander アカウントのいずれかに、新しい DICT キーを登録します。
delete_dict_key	加盟店向けに以前登録した DICT キーを削除（登録解除）します。
download_boleto_pdf	登録済み boleto の PDF（再発行分／segunda via）を取得します。
get_account_balance	Santander の加盟店アカウントの現在の利用可能残高と拘束残高を取得します。
send_ted	Santander の加盟店アカウントから、他行の口座への TED 振込を開始します。
transfer_internal	2つの Santander アカウント間で振り替えます（TEF／同一金融機関）。
create_openfinance_consent	第三者に対するデータアクセスまたは支払い開始のため、Open Finance の同意（BACEN 規制）を作成します。
arrecadacao_pay	Santander Arrecadação／Pagamento de Contas 経由で、公共料金、税金、またはコンセッショネアの請求書を支払います。

インストール

npm install @codespar/[email protected]

環境変数

SANTANDER_CLIENT_ID="..."       # OAuth client_id from Santander's Developer Portal
SANTANDER_CLIENT_SECRET="..."   # OAuth client_secret
SANTANDER_CERT_PATH="/abs/path/to/client.crt"   # mTLS client certificate
SANTANDER_KEY_PATH="/abs/path/to/client.key"    # mTLS private key
SANTANDER_ENV="sandbox"                         # or "production" (default: sandbox)

認証

すべての呼び出しで、次の2つの要素が両方とも必要です。

1. OAuth2 client_credentials — サーバーはtrust-open（またはtrust-sandbox）ゲートウェイの/auth/oauth/v2/tokenにPOSTし、有効期限の約60秒前までベアラートークンをキャッシュして、下流の呼び出しにAuthorization: Bearer <token>を付与します。
2. mTLS — BACENはPix v2で相互TLSを必須としており、Santanderのtrust-openゲートウェイは製品ファミリー全体でこれを適用します。サーバーは設定したパスからクライアント証明書と秘密鍵を読み込み、Nodeのhttps.Agentを構築して、すべてのリクエストを経由させます。

加盟店契約の締結後、Santander Developer Portalから証明書と鍵のバンドルを取得します。これらはOAuth認証情報とは別のものです。

Cobrança：ワークスペースモデル

SantanderのCobrança v2はワークスペース単位です。ボレートを登録する前に、Developer Portalで1つ以上のworkspace_idをプロビジョニングします。それぞれにコンベニオ、ボレート／Pixの請求方式、Webhook URLが紐付けられます。create_boleto、get_boleto、cancel_boletoの各ツールは、いずれもworkspace_id引数を受け取ります。

実行

# stdio (default)
npx @codespar/mcp-santander

# HTTP transport
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-santander

注意事項

• Pix／Arrecadação／Extratoのパスは未検証です。 src/index.tsのTODO(verify)マーカーを参照してください。オンボーディング済みの加盟店は、ポータルから発行されたOpenAPI仕様に照らして検証し、PRを作成してください。
• Cobrançaのキャンセルは、status: "BAIXADO"を指定するPATCHとしてモデル化されています。コンベニオ固有のキャンセルの意味は異なる場合があります。
• Arrecadaçãoのバーコード検証は、このアルファ版ではサーバー側で行います。クライアント側のmod-10／mod-11チェックにはまだ対応していません。

エンタープライズ

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

ライセンス

MIT