monapay-mcp

monapay-mcp

Claude Code、Cursor、Codex などの AI コーディングエージェント（または任意の MCP クライアント）が、コーディング中に MONA Pay を操作できる MCP サーバーです。銀行口座の連携、チェックアウトリンクや VietQR コードの作成、入金の確認、Webhook・メール・Zalo グループ通知の設定とテスト、Webhook 署名の検証ができます。

npm では monapay-mcp として、MCP Registry では vn.monapay/monapay-mcp として公開されています。

インストール

Node.js 18 以降と MONA Pay API キー（MONA Pay ダッシュボードで作成するクライアント ID とクライアントシークレット）が必要です。

npx -y monapay-mcp   # starts the server over stdio

Claude Code

claude mcp add monapay \
  -e MONAPAY_CLIENT_ID=your_client_id \
  -e MONAPAY_CLIENT_SECRET=your_client_secret \
  -- npx -y monapay-mcp

Cursor（.cursor/mcp.json）と Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "monapay": {
      "command": "npx",
      "args": ["-y", "monapay-mcp"],
      "env": { "MONAPAY_CLIENT_ID": "client_id", "MONAPAY_CLIENT_SECRET": "client_secret" }
    }
  }
}

Codex（~/.codex/config.toml）

[mcp_servers.monapay]
command = "npx"
args = ["-y", "monapay-mcp"]
env = { MONAPAY_CLIENT_ID = "client_id", MONAPAY_CLIENT_SECRET = "client_secret" }

設定

変数	必須	意味
MONAPAY_CLIENT_ID	はい（推奨）	ダッシュボードで作成した API キーの client_id
MONAPAY_CLIENT_SECRET	はい（推奨）	client_secret。一度だけ表示されます。OAuth トークンの取得と書き込み操作の認証に使用されます
MONAPAY_USERNAME	レガシー	MONA Pay のユーザー名。クライアント認証情報が設定されていない場合のみ使用されます
MONAPAY_PASSWORD	レガシー	パスワード。2FA が有効なアカウントでは使用できません
MONAPAY_BASE_URL	いいえ	デフォルトは https://api.monapay.vn です

2FA が有効なアカウントはパスワードでログインできないため、ユーザー名とパスワードよりもクライアント認証情報の使用を推奨します。

使用方法

ツール

ツール	内容
monapay_quickstart	エントリーポイントです。アカウントの状態（銀行口座／VA の連携、Webhook の設定）を確認し、次の手順を返します
monapay_whoami	接続を確認し、アカウント名とプランを返します
monapay_me	ログイン中のアカウントのプロフィールです
monapay_link_bank_start · monapay_link_bank_verify_otp	ACB アカウントを連携し、仮想口座を作成します（最初の OTP）
monapay_notification_register · monapay_notification_verify_otp	入金通知を有効にします（2 回目の OTP）
monapay_list_bank_accounts · monapay_list_virtual_accounts	連携済みの銀行口座と、その仮想口座（VA）です
monapay_get_payment_profile · monapay_set_payment_profile	ホスト型チェックアウトページで使用するプロフィールを表示または設定します
monapay_create_checkout · monapay_get_checkout · monapay_list_checkouts · monapay_cancel_checkout	ホスト型チェックアウトセッションを作成、確認、絞り込み、キャンセルします
monapay_create_qr · monapay_cancel_qr	注文用の動的 VietQR を作成またはキャンセルします
monapay_list_transactions	VA への入金取引（1 ページあたり最大 100 件）を照合用に取得します
monapay_get_transaction	VA 内の transaction_code または ID で入金取引を 1 件検索します
monapay_get_transactions_summary	指定した期間の入金合計、取引件数、日別データを取得します
monapay_sandbox_transaction	偽の入金取引を作成します。Webhook、Telegram、メール、Zalo が実際の取引と同様に送信されます。VA がない場合は、サンドボックス VA が発行されます
monapay_list_webhooks · monapay_create_webhook · monapay_update_webhook · monapay_delete_webhook	Webhook 設定（NONE、API_KEY、HMAC_SHA256。HMAC を推奨）
monapay_test_webhook · monapay_webhook_logs · monapay_webhook_stats	テスト用 Webhook の送信、配信履歴、成功率／P95 を確認します
monapay_list_email_configs · monapay_create_email_config · monapay_update_email_config · monapay_delete_email_config	1～10 件の宛先を設定できるメール通知の設定です
monapay_verify_email · monapay_resend_email_verification · monapay_test_email	6 桁のコードで宛先を確認し、コードを再送信し、テストメールを送信します
monapay_email_logs · monapay_email_stats	配信メタデータ、成功率／P95、エラーグループを確認します
monapay_list_email_suppressions · monapay_remove_email_suppression	抑制対象のアドレスを表示および削除します
monapay_list_zalo_groups · monapay_create_zalo_group · monapay_update_zalo_group · monapay_delete_zalo_group	Zalo グループ通知の設定です
monapay_test_zalo_group · monapay_zalo_group_logs	テストメッセージを送信し、Zalo グループの配信履歴を確認します
monapay_retry_transaction	取引の Webhook または Telegram 通知を再送信します
monapay_generate_key	新しい client_secret を生成します
monapay_rotate_key	現在のキーが漏えいした可能性がある場合に、シークレットをローテーションします
monapay_verify_signature	ネットワーク通信なしで、Webhook 署名をローカルで検証します
monapay_generate_webhook_snippet	サンプルペイロード付きの PHP、Node、Python 用 Webhook 受信コードです

リソースとプロンプト

• monapay://docs/llms：MONA Pay ドキュメントの機械可読インデックスです。
• monapay://docs/{slug}：ドキュメントページを Markdown 形式で取得します。例：monapay://docs/webhooks/tich-hop-webhook。
• プロンプト integrate-monapay（引数 language、framework）：エージェントが現在のプロジェクトに MONA Pay を統合するための 6 ステップの計画です。

例

「MONA Pay を使って、この Laravel サイトに銀行振込の自動確認を組み込んでください。」

エージェントは monapay_whoami を呼び出し、monapay_generate_webhook_snippet(language="php") で受取人コードを取得して、エンドポイントをプロジェクトに書き込みます。monapay_create_webhook(auth_type="HMAC_SHA256", secret_key=...) でエンドポイントを登録し、monapay_test_webhook を実行します。monapay_webhook_logs を読み取ってエンドポイントが 200 を返すことを確認した後、注文ごとに monapay_create_checkout を使用し、CHECKOUT_PAID を待ちます。

OTP を使って銀行口座を連携する

ACB は、口座名義人の登録済み電話番号に各 OTP を送信します。エージェントは手順 2 と 4 でユーザーに確認する必要があり、OTP を推測してはいけません。

1. ACB の口座番号、電話番号、顧客種別、VA プレフィックス、識別子を指定して monapay_link_bank_start を呼び出します。acb_request_id が返され、ACB から最初の OTP が送信されます。
2. ユーザーに OTP を尋ねてから monapay_link_bank_verify_otp を呼び出します。virtual_account_id と VA 番号が返されます。
3. virtual_account_id を指定して monapay_notification_register を呼び出します。ACB から 2 つ目の OTP が送信されます。
4. ユーザーに 2 つ目の OTP を尋ねてから monapay_notification_verify_otp を呼び出します。以降、入金は設定済みの Webhook に転送されます。

OTP が間違っているか、有効期限が切れている場合は、前の手順をもう一度呼び出して新しいコードを取得してください。

Zalo グループ通知

グループには MONA ボット（Gấu Mona）が参加している必要があります。このボットは MONA チームによって追加されます。group_id は 10～25 桁で、MONA Account/PMS から取得します。

group_id、わかりやすい名前、受信するイベント（TRANSACTION_IN、CHECKOUT_PAID、WEBHOOK_FAILED、VA_CREATED）を指定して monapay_create_zalo_group を呼び出します。対象を 1 つの virtual_account_id に限定できます。monapay_test_zalo_group でテストを送信し、monapay_zalo_group_logs で配信状況を確認できます。

Zalo は Markdown を表示しないため、message_template はプレーンテキストにする必要があります。{amount}、{description}、{virtual_account_number}、{transaction_code}、{transfer_date} に対応しており、{{amount}} 形式も使用できます。

キーのローテーション

monapay_rotate_key は、現在のシークレットを使って MONAPAY_CLIENT_ID に一致するキーをローテーションします。古いシークレットは直ちに使用できなくなります。MCP の設定で MONAPAY_CLIENT_SECRET を更新し、クライアントを再起動してください。

Webhook の署名

X-Mona-Signature: sha256=<hex>。ここで、hex = HMAC-SHA256(secret, "<X-Mona-Timestamp>.<raw_body>") です。タイムスタンプが現在時刻から 300 秒以上ずれているリクエストは拒否し、定時間比較を行ってください。再試行時も transaction_code は変わらないため、重複排除キーとして使用してください。

開発

npm install
npm test     # build + node --test

# Calls a few read-only tools against a real account
MONAPAY_CLIENT_ID=... MONAPAY_CLIENT_SECRET=... MONAPAY_BASE_URL=https://api.monapay.vn npm run smoke

エージェントガイド：https://monapay.vn/ai-agent · ドキュメント：https://monapay.vn/docs

ライセンス

MIT

MONA Pay は The MONA Group の MONA Cloud の一部です。