mcp-openpay

@codespar/mcp-openpay

Openpay 用の MCP サーバーです。BBVA 傘下のメキシコの決済ゲートウェイです。

Openpay は、メキシコのオンライン加盟店にとって、Conekta に対抗する BBVA 支援の主要な決済サービスです。カタログに @codespar/mcp-conekta と並べて追加することで、メキシコの「二大」ゲートウェイをカバーし、エージェントが BBVA の決済ネットワーク（SPEI、OXXO、国内カード）を利用できるようになります。このカタログにおける差別化要素は、ネイティブなサブスクリプション（プランと顧客ごとの定期請求）とマーケットプレイスへの支払いです。

ツール（23）

ツール	用途
create_charge	支払いを作成します。
get_charge	支払いを取得します。
capture_charge	以前に承認された支払いをキャプチャします（元の支払いで capture=false が指定されている場合）。
refund_charge	キャプチャ済みの支払いを返金します。
create_customer	顧客レコードを作成します。
get_customer	Openpay の顧客 ID で顧客を取得します。
list_customers	オプションのフィルターを指定して顧客を一覧表示します。
create_card	カードをトークン化します。
delete_card	トークン化されたカードを削除します。
create_plan	サブスクリプションプランを作成します。
create_subscription	顧客をプランに登録します。
create_payout	銀行口座に MXN を支払います。
update_customer	保存済みの顧客を更新します（PUT /customers/{id}）。
delete_customer	顧客を削除します（DELETE /customers/{id}）。
get_card	トークン化されたカードを取得します。
list_cards	トークン化されたカードを一覧表示します。
create_bank_account	顧客の銀行口座を保存します（POST /customers/{customer_id}/bankaccounts）。
delete_bank_account	保存済みの顧客の銀行口座を削除します（DELETE /customers/{customer_id}/bankaccounts/{id}）。
cancel_subscription	顧客のサブスクリプションを解約します（DELETE /customers/{customer_id}/subscriptions/{id}）。
list_payouts	支払いを一覧表示します。
create_webhook	Webhook エンドポイントを登録します（POST /webhooks）。
list_webhooks	設定済みの Webhook サブスクリプションを一覧表示します（GET /webhooks）。
delete_webhook	Webhook サブスクリプションを削除します（DELETE /webhooks/{id}）。

インストール

npm install @codespar/mcp-openpay

環境変数

OPENPAY_MERCHANT_ID="..."  # merchant id (part of the API URL path)
OPENPAY_PRIVATE_KEY="..."  # private API key — secret
OPENPAY_ENV="sandbox"      # 'sandbox' (default) | 'production'

認証

HTTP Basic 認証です。秘密鍵をユーザー名として指定し、パスワードは空にします。

Authorization: Basic base64(OPENPAY_PRIVATE_KEY + ":")
Content-Type: application/json

サーバーが Base64 エンコードを自動で処理するため、設定する環境変数は 3 つだけです。

ベース URL

環境	ホスト
sandbox（デフォルト）	https://sandbox-api.openpay.mx/v1/{merchant_id}
production	https://api.openpay.mx/v1/{merchant_id}

実行

# stdio (default — for Claude Desktop, Cursor, etc)
npx @codespar/mcp-openpay

# HTTP (for server-to-server testing)
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-openpay

スコープに関する注意事項

Openpay の複数のリソースは、加盟店スコープまたは顧客スコープのいずれでも指定できます。ツールでは、オプションの customer_id パラメーターを使用してこれを指定します。

• create_charge、get_charge、capture_charge、refund_charge — customer_id が設定されている場合は /customers/{customer_id}/... にルーティングされ、設定されていない場合は /... にルーティングされます。
• create_card、delete_card — 同じ動作です。
• create_payout — 顧客スコープで支払うには、顧客の requires_account=true が必要です。
• create_subscription — API で顧客スコープが必須です（プランは加盟店スコープですが、サブスクリプションは常に顧客ごとに設定されます）。

PCI の適用範囲

Openpay.js によるクライアント側のトークン化を優先し、生成された token_id / source_id をサーバーに渡してください。生の PAN や CVV をサーバー側に送信するのは、PCI-DSS に準拠している場合に限ってください。

ドキュメント

https://documents.openpay.mx/en/api

エンタープライズ

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

ライセンス

MIT