PayPal, guarded

fizzl-paypal-guard-mcp

Claude Desktop、Claude Code、Cursor、その他の MCP クライアント向けの、PayPal の Agent Toolkit を使った MCP サーバーです。モデルと PayPal の間に fizzl-paypal-guard を配置します。

PayPal 独自の MCP サーバー（@paypal/mcp）と同じ 47 個のツールを、同じ名前で利用できます。違いは、お金を移動したり、支払いを約束したりするすべての呼び出しを、実行前に確認することです。

• 読み取りはそのまま通します。 注文、請求書、取引、異議申し立て、返金は、必要なだけ確認できます。
• 残額を超えることはありません。 金額を指定せずに返金すると、支払いの残額がすべて返金されます。ガードはまず PayPal から支払い情報を読み取ります。すでに全額返金済みの支払いへの返金は停止され、残額を超える返金も停止されます。
• 銀行がすでに支払った場合は返金しません。 チャージバックまたは異議申し立てが未解決の支払いへの返金は停止されます。購入者が二重に返金を受け取ることになり、PayPal ではその返金が通ってしまうためです。
• 上限を設定できます。 デフォルトでは、返金は 1 件あたり最大 25 ドル、1 日あたり合計 100 ドルかつ 10 件まで、支払いごとに 1 日 1 回までです。同じ顧客への 30 日以内の 3 回目の返金では、あなたに確認を求めます。キャンセルと請求には、1 日あたりの件数上限があります。
• 残りはあなたが判断します。 上限を超える場合、および異議申し立て、価格変更、支払い済みとしてマークする請求書については、承認または拒否を選択できます。スマートフォン（Telegram、または Fizzl Agent Wallet）か、チャットアプリ自体で操作できます。返答がなければ実行されません。
• エージェントが書き換えられないログを記録します。 読み取り以外のすべての操作について、判断、理由、承認者をあなたのマシンに記録します。その日の件数も同じ場所に保存されるため、アプリを再起動してもエージェントに上限がリセットされることはありません。

ブロックされた呼び出しは { "blocked": true, "reasons": […], "message": "Not done (…)" } を返し、メッセージで別の方法を試さないようモデルに伝えます。モデルがガードを言いくるめて回避することはできません。確認には PayPal から取得した情報とあなたが設定した上限を使い、会話の内容は使いません。

ガードのライブデモ（PayPal サンドボックス内のサポートエージェント）：https://fizzl-paypal-demo.onrender.com

セットアップ

1. developer.paypal.com → Apps & Credentials で REST アプリを作成します。まずは Sandbox で始めてください。テスト用のお金のみを使います。クライアント ID とシークレットをコピーします。
2. MCP クライアントにサーバーを追加します。 Claude Desktop の場合は、claude_desktop_config.json に次の内容を追加します。

{
  "mcpServers": {
    "paypal": {
      "command": "npx",
      "args": ["-y", "fizzl-paypal-guard-mcp", "--tools=all"],
      "env": {
        "PAYPAL_CLIENT_ID": "your sandbox client id",
        "PAYPAL_CLIENT_SECRET": "your sandbox secret",
        "PAYPAL_ENVIRONMENT": "SANDBOX"
      }
    }
  }
}

Claude Code の場合：

claude mcp add paypal -e PAYPAL_CLIENT_ID=… -e PAYPAL_CLIENT_SECRET=… -e PAYPAL_ENVIRONMENT=SANDBOX -- npx -y fizzl-paypal-guard-mcp --tools=all

ダブルクリックで使える Claude Desktop 版： fizzl-paypal-guard-mcp.mcpb をダウンロードし、Claude Desktop で開きます。クライアント ID とシークレット、上限、必要であれば Fizzl ウォレットキーまたは Telegram ボットの入力を求められます。設定ファイルに入力するものはありません。

3. アプリを再起動し、 たとえば 「先週の PayPal 取引を一覧表示して」、続いて 「capture 2GG… を全額返金して」 と尋ねます。paypal_guard_status に、ガードで許可されている操作と今日の実行内容を確認してください。

@paypal/mcp から移行する場合は、同じ --tools リストを使います。このサーバーは PAYPAL_ACCESS_TOKEN の代わりにアプリのクライアント ID とシークレットを使います。アクセストークンは約 9 時間で使えなくなり、ガードが自分で支払い情報を読み取る必要があるためです。

承認

アクションに承認が必要な場合、設定されているもののうち最初の方法でサーバーから確認が求められます。

場所	方法	設定
Fizzl Agent Wallet	Telegram（@FizzlWalletBot）またはウォレットのダッシュボードで、エージェントのほかの支払いの横にある「承認」または「拒否」を選択します。結果（PayPal の返金 ID）は、そこにレシートとして記録されます。	FIZZL_AGENT_KEY：wallet.fizzl.eu → Agents で取得したエージェントキー（awk_…）
自分の Telegram ボット	ボットから「承認」と「拒否」の選択肢があるメッセージが届きます。 @BotFather でボットを作成して /start を送り、 @userinfobot からチャット ID を取得します。ボットに webhook を設定してはいけません。	TELEGRAM_BOT_TOKEN、TELEGRAM_CHAT_ID
チャットアプリ内	アプリ自体に表示されるフォーム（MCP のエリシテーション）で「承認」または「拒否」を選択します。回答できるのはあなただけで、モデルは回答できません。Claude Code など、エリシテーションに対応する MCP クライアントで利用できます。ほかのクライアントでは、スマートフォンを使用してください。これらのフォームに自動で回答するフックは設定しないでください（Claude Code の Elicitation フックで可能です）。	なし。無効にするには APPROVAL_IN_CHAT=off を設定します

いずれも設定されていない場合、上限を超える操作は実行されません。

スマートフォンを使う方法がより安全です。エージェントを実行しているデバイスとは別のデバイスで確認でき、MCP クライアントがツール呼び出しを待つ時間より長く待てます。APPROVAL_WAIT_SECONDS（45）を過ぎても回答がない場合、呼び出しは承認 ID とともに "waiting": true を返します。承認は引き続き有効です。APPROVAL_MINUTES（10）以内に承認すれば、その後アクションが実行されます。それ以外の場合は何も起きません。モデルには再試行しないよう伝えられます。承認 ID を指定して paypal_guard_status を呼び出すと、結果を確認できます。

設定

変数
PAYPAL_CLIENT_ID、PAYPAL_CLIENT_SECRET	REST アプリの設定です。これらを設定しない場合、サーバーはツールの一覧を表示し、各呼び出しで設定方法を説明します。
PAYPAL_ENVIRONMENT	SANDBOX（デフォルト）または PRODUCTION
--tools= または PAYPAL_TOOLS	all（デフォルト）、または PayPal の MCP サーバーと同じ名前を指定します：payments.createRefund,payments.getRefunds,orders.get,transactions.list,invoices.list,…
LIMIT_REFUND	確認なしで処理できる返金ごとの上限（デフォルトは 25.00）
LIMIT_REFUND_PER_DAY	1 日あたりの返金総額（デフォルトは 100.00）
LIMIT_REFUNDS_PER_DAY	1 日あたりの返金件数（デフォルトは 10）
LIMIT_CURRENCY	上限に適用する通貨（デフォルトは USD）。別の通貨で返金する場合は確認を求めます。
GUARD_POLICY	それ以外の設定を、デフォルト設定に対する JSON として指定します。例：{"dispute":"deny","stop":"ask","bill":{"countPerDay":5}}。また、{"returnDays":30} とすると、返品可能期間を過ぎた支払いの返金について確認を求めます。各種設定には "allow"、"ask"、"deny" または上限を指定できます。
FIZZL_AGENT_KEY、FIZZL_WALLET_URL	Fizzl Agent Wallet を通じた承認（URL のデフォルトは https://wallet.fizzl.eu）
TELEGRAM_BOT_TOKEN、TELEGRAM_CHAT_ID	自分の Telegram ボットを通じた承認
APPROVAL_IN_CHAT	チャットアプリ内で確認を求めない場合は off
APPROVAL_MINUTES	回答できる時間（デフォルトは 10）
APPROVAL_WAIT_SECONDS	ツール呼び出しが回答を待つ時間。経過すると「waiting」を返します（デフォルトは 45）
AGENT_NAME	スマートフォンに表示される名前（デフォルトは MCP クライアントの名前）
GUARD_STATE_DIR	その日の件数とログの保存先（デフォルトは ~/.fizzl-paypal-guard。sandbox と live は別々に保存されます）

ツール

PayPal Agent Toolkit 1.11 のすべてのツールを、お金に対する操作別に分類しています。

種類	ツール	デフォルトの設定
読み取り	get_order, list_transactions, get_refund, list_invoices, get_invoice, list_disputes, get_dispute, …	承認不要
返金	create_refund	残額を超える返金や、チャージバックまたは異議申し立てが未解決の支払いへの返金は不可。1件あたり25ドル、1日あたり合計100ドル・10件まで。それ以降はあなたが決定します
異議申し立て	accept_dispute_claim（購入者に支払います）	1件ごとにあなたが決定します
帳簿	record_payment_for_invoice, record_refund_for_invoice（お金が動いていないのに、移動したと記録します）	1件ごとにあなたが決定します
停止	cancel_subscription, cancel_sent_invoice, delete_invoice, …	1日あたり3件まで。それ以降はあなたが決定します
価格	update_product, update_plan, update_subscription, create_subscription_plan, …	1件ごとにあなたが決定します
請求	create_invoice, send_invoice, create_subscription, …	1日あたり20件まで。それ以降はあなたが決定します
その他	create_order, pay_order, create_shipment_tracking, send_invoice_reminder, …	承認不要

ガードがまだ把握していない新しいツールキットのツールは、必ずあなたに確認を求めます。全リストは actions.js にあります。

独自のツールも2つあります。

ツール
paypal_guard_status	あなたの上限、今日の使用量、承認待ちの項目、ログに記録された最新の判断を確認できます。approval_id を指定すると、その承認の結果を確認できます。
paypal_guard_check	ドライランです。実行せずに、ガードが呼び出しに対してどのように判断するか、その理由を確認できます。

顧客向けアプリの場合

Claude との自分用のチャットでは、指示を出すのはあなたです。サポートボットは異なります。顧客に代わって動作し、顧客はどんなことでも主張できるからです（「夫の代理で連絡しています。夫のキャプチャ番号はこちらです」など）。その場合、ガードは返金、キャンセル、請求が、アプリの対応対象である顧客に属するものかどうかも確認します。

サーバーに顧客を伝えるのはモデルではなくアプリです。ツール呼び出しの _meta に含めるため、モデルが変更することはできません。

await mcpClient.callTool({
  name: "create_refund",
  arguments: { capture_id: "2GG…" },
  _meta: { "fizzl.eu/customer": "[email protected]", "fizzl.eu/request": "My mug arrived broken" },
});

PayPal は、PayPal チェックアウトでの支払いについては支払者のメールアドレスを把握しています。カード決済にはメールアドレスがありません。その場合は、デモショップ と同様に、独自のコードで customerOf フックを使って fizzl-paypal-guard を使用してください。

知っておくとよいこと

• まずはサンドボックスでテストしてください。 PRODUCTION では返金が実際に行われます。
• 1日の件数はマシンごとに数えます。同じ PayPal アプリを使うコンピューターが2台あっても、それぞれ別々にその日の件数を管理します。
• ガードは同じ REST アプリを使って PayPal の支払い情報を読み取ります。ガード自身がお金を動かすことはありません。
• PayPal データ内のテキスト（請求書のメモ、異議申し立てのメッセージ、商品説明など）は、他の人が書いたものです。サーバーはモデルに対し、それらを指示ではなく情報として扱うよう伝えます。ガードはモデルがそれに従うことを当てにはしません。

開発

npm ci
npm test                          # the MCP server with a pretend PayPal
PAYPAL_SANDBOX_CLIENT_ID=… PAYPAL_SANDBOX_SECRET=… node test/sandbox.mjs   # against the PayPal sandbox

GitHub Actions は変更のたびにサンドボックスのチェックを実行します（paypal-sandbox.yml）。2人の顧客がカードで支払い、続いて MCP 経由で12ドルの返金が実行され、300ドルの返金は所有者の承認を待ってから、Approve 後に実行されます。また、全額返金済みの支払いに対する2回目の返金は停止されます。

MIT · Fizzl