Toss Payments

@appmonster/mcp-toss-payments

Toss Payments（토스페이먼츠）のコア API 用 MCP サーバーです。エージェントは決済の照会、取引の照合、精算情報の確認ができます。また、実際のお金が動く唯一のツールであるキャンセル／返金は、人間の承認を経て実行されるように設計されています（OK Agent）。

Toss Payments MCP サーバー — 決済の照会、取引履歴、精算、キャンセル／返金（承認ゲート）。

ツール

ツール	アクセス	機能
toss_get_payment	読み取り	paymentKey または orderId で決済を1件照会：ステータス、金額、残高、決済手段、キャンセル履歴、領収書 URL
toss_cancel_payment	書き込み	全額／一部キャンセル。仮想口座の場合は返金口座が必須です。Idempotency-Key を自動付与
toss_list_transactions	読み取り	期間別の取引（承認・キャンセル）一覧。最大5000件、startingAfter カーソル
toss_list_settlements	読み取り	精算情報（手数料・付加価値税・支払額）。売上日／支払日を基準にし、合計を含みます

セットアップ

1. https://developers.tosspayments.com → 開発者情報 → API キー。まずは test_sk_… を使ってください（テスト決済データで動作します）。
2. MCP クライアントの設定：

{
  "mcpServers": {
    "toss-payments": {
      "command": "npx",
      "args": ["-y", "@appmonster/mcp-toss-payments"],
      "env": { "TOSS_SECRET_KEY": "test_sk_…" }
    }
  }
}

キャンセルの人間による承認（ライブキーを使う場合は強く推奨）

"OKAGENT_API_KEY": "ok_…"

これを設定しなくても、書き込みツールが確認なしで実行されることはありません。最初の呼び出しではプレビューと confirm_token が返され、チャットで同意した後にのみ、エージェントが再度呼び出します。OK Agent のキー（無料、月200件）を使うと、代わりにリクエストがスマートフォンに届き、KakaoTalk で承認でき、ログも残ります。KMCP_WRITE_MODE=direct を設定すると、完全に信頼できるスクリプトでは確認を無効にできます。

live_sk_ キーを使用していて、承認フックが設定されていない場合、サーバーは起動時に警告を表示します。

安全上の注意

• toss_cancel_payment は取り消しできません。ツールの説明では、エージェントに最初に toss_get_payment を呼び出して balanceAmount を確認するよう指示しています。
• すべてのキャンセルには Idempotency-Key（UUID または呼び出し元が指定したキー）が付与されるため、呼び出しを再試行しても二重に返金されません。Toss 側でのキーの有効期間は15日間です。
• テストキーを使うサーバーでは、すべてのツールの説明に [TEST KEY — sandbox data] が付与されるため、エージェントがサンドボックスの数値を実際の売上と取り違えることはありません。

開発

pnpm --filter @appmonster/mcp-toss-payments test