Qut Pay (Kaspi QR payments)

@qutpay/mcp — Qut Pay MCP サーバー

Model Context Protocol サーバーです。Qut Pay を利用して、AI エージェント（Claude Code、Claude Desktop、Cursor、Windsurf、VS Code Copilot、ChatGPT developer mode…）が Kaspi QR 請求書を作成し、ステータスを確認し、返金を行い、Qut Pay API を通じてサンドボックスで一連の流れをテストできます。カザフスタンのみ、KZT のみが対象です。Qut Pay は独立したサービスであり、Kaspi Bank とは提携していません。

インストール

Qut Pay の管理画面（https://qut.kz/app → Integrations → API keys）で取得した API キーが必要です。まずはサンドボックスキー（qp_test_…）を使用してください。実際のお金は動かず、支払いはシミュレーションされます。

Claude Code：

claude mcp add qutpay -e QUTPAY_API_KEY=qp_test_… -- npx -y @qutpay/mcp

Cursor のワンクリック追加：Cursor に追加（追加後にキーを設定してください）。Cursor ／ Windsurf ／ Claude Desktop ／ VS Code（mcp.json、claude_desktop_config.json）：

{
  "mcpServers": {
    "qutpay": {
      "command": "npx",
      "args": ["-y", "@qutpay/mcp"],
      "env": { "QUTPAY_API_KEY": "qp_test_…" }
    }
  }
}

キーは環境からのみ読み込まれ、サーバーによって表示されることはありません。任意の QUTPAY_BASE_URL（既定値は https://api.qut.kz）も設定できます。

リモート（ホスト型）エンドポイント

インストール不要です：https://api.qut.kz/mcp（Streamable HTTP）。キーは Authorization: Bearer qp_… で指定します。Claude Code の場合：claude mcp add --transport http qutpay https://api.qut.kz/mcp --header "Authorization: Bearer qp_test_…"。Cursor／VS Code の mcp.json の場合：{ "url": "https://api.qut.kz/mcp", "headers": { "Authorization": "Bearer qp_test_…" } }。キーなしの場合、エンドポイントはツールの一覧を表示してドキュメントを提供します。ツールの呼び出しには unauthorized が返されます。

ツール

ツール	機能
qutpay_account	組織、モード（sandbox／live）、料金プランと上限、レジ係、プロバイダーのステータスを確認します。最初に呼び出してください
qutpay_create_invoice	請求書を作成します（QR、または kind: "phone" を指定して顧客の Kaspi.kz アプリに送信）。payUrl、qrImageUrl、deepLink、expiresAt を返します。注文ごとに idempotencyKey を指定してください
qutpay_get_invoice	請求書 1 件のステータスを確認します（live: true を指定すると、その時点で Kaspi に問い合わせます）
qutpay_list_invoices	フィルター（status、externalOrderId、from／to、最大 50 件の limit）を指定して一覧を取得します
qutpay_cancel_invoice	未完了の請求書を閉じます
qutpay_refund_invoice	全額または一部を返金します（scope refunds:write）。live キーの場合は confirm: true が必要です
qutpay_simulate_payment	サンドボックス専用：請求書を支払い済み／失敗／期限切れとして設定します。webhook は実際に配信されます
qutpay_list_subscriptions、qutpay_get_subscription	定期請求のスケジュールを確認します（scope subscriptions:manage）

リソース：qutpay://skill（エージェントスキル — 統合手順）、qutpay://docs/integration、qutpay://docs/webhook-verify、qutpay://docs/errors、qutpay://docs/openapi。プロンプト：integrate-checkout（スタック）、verify-sandbox（金額）。

API キーと webhook エンドポイントは、意図的に MCP サーバーから管理できないようになっています。加盟店が管理画面で作成し、エージェントがそれらを要求します。

典型的なセッション

1. qutpay_account → モードが sandbox であることを確認します。
2. qutpay_create_invoice { amount: 100, externalOrderId: "test-1", idempotencyKey: "test-1" } → payUrl が返されます。
3. qutpay_simulate_payment { id } → paid。加盟店の webhook に invoice.paid が届きます。
4. qutpay_get_invoice { id } → paid。

ドキュメント

• エージェントスキル：https://api.qut.kz/SKILL.md · 統合ガイド：https://api.qut.kz/for-ai · OpenAPI：https://api.qut.kz/openapi.json
• ガイド（ru/kk/en）：https://api.qut.kz/docs/guide/mcp
• ステータスページ：https://status.qut.kz · トラストセンター：https://qut.kz/en/trust/

MIT。