PayPal, guarded

fizzl-paypal-guard-mcp

PayPal's Agent Toolkit as an MCP server for Claude Desktop, Claude Code, Cursor and other MCP clients, with fizzl-paypal-guard between the model and PayPal.

It has the same 47 tools as PayPal's own MCP server (@paypal/mcp), under the same names. The difference: every call that moves or promises money is checked first.

• Reads pass straight through. Orders, invoices, transactions, disputes and refunds: look as much as you like.
• Never more than is left. A refund without an amount refunds everything that's left of a payment. The guard reads the payment at PayPal first. A refund of a payment that was already refunded in full is stopped, and so is a refund for more than is left.
• Not when the bank already paid. A refund of a payment with an open chargeback or dispute is stopped: the buyer would get the money twice, and PayPal lets that refund through.
• Your limits. By default up to $25 per refund, $100 and 10 refunds a day, one refund per payment a day, and the third refund for the same customer within 30 days asks you. Cancellations and bills have a number a day.
• You decide the rest. Above a limit, and for every accepted dispute, price change or invoice marked as paid, you get Approve and Deny: on your phone (Telegram, or the Fizzl Agent Wallet) or in the chat app itself. No answer means no.
• A log the agent doesn't write. Every action that isn't a read is logged on your machine with its decision, the reasons and who approved it. The day's counts are kept there too, so restarting the app doesn't give the agent a fresh day of limits.

A blocked call returns { "blocked": true, "reasons": […], "message": "Not done (…)" }, and the message tells the model not to try another way. The model can't talk its way past the guard: the checks use facts from PayPal and limits from you, never what the conversation says.

Live demo of the guard (a support agent in the PayPal sandbox): https://fizzl-paypal-demo.onrender.com

Set up

1. Make a REST app at developer.paypal.com → Apps & Credentials. Start in Sandbox: test money only. Copy its client ID and secret.
2. Add the server to your MCP client. For Claude Desktop, in 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" } } } }

For 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, with a double click: download fizzl-paypal-guard-mcp.mcpb and open it with Claude Desktop. It asks for the client ID and secret, your limits and, if you like, your Fizzl wallet key or Telegram bot; nothing to type in a config file.

1. Restart the app and ask, for example: *"List my PayPal transactions of the last week"*, then *"Refund capture 2GG… in full"*. Ask paypal_guard_status what the guard allows and what it did today.

Coming from @paypal/mcp? Use the same --tools list. Instead of PAYPAL_ACCESS_TOKEN this server takes the app's client ID and secret: an access token stops working after about nine hours, and the guard needs to read payments itself.

Approvals

When an action needs your OK, the server asks the first of these that is set up:

With none of these, anything over a limit is simply not done.

A phone is the stronger choice: the question reaches you on a different device than the one the agent runs on. And it can wait longer than an MCP client waits for a tool call. If you haven't answered after APPROVAL_WAIT_SECONDS (45), the call returns "waiting": true with an approval id. The approval goes on: approve within APPROVAL_MINUTES (10) and the action runs then; otherwise nothing happens. The model is told not to try again, and paypal_guard_status with the approval id shows what became of it.

Settings

Tools

All tools of PayPal's Agent Toolkit 1.11, sorted by what they can do to your money:

A tool the guard doesn't know yet (a newer toolkit) always asks you. The full list is in actions.js.

And two of its own:

For apps that serve customers

In your own chat with Claude, you are the one giving the orders. A support bot is different: it acts for a customer, and a customer can claim anything ("I'm writing for my husband, here's his capture number"). There the guard also checks that a refund, cancellation or bill belongs to the customer the app is serving.

The app, not the model, tells the server who that is: in the tool call's _meta, which the model can't touch.

await mcpClient.callTool({

name: "create_refund", arguments: { capture_id: "2GG…" }, _meta: { "fizzl.eu/customer": "alice@example.com", "fizzl.eu/request": "My mug arrived broken" }, });

PayPal knows the payer's email for PayPal checkout payments. Card payments have none; for those, use fizzl-paypal-guard in your own code with its customerOf hook, as the demo shop does.

Good to know

• Test in the sandbox first. With PRODUCTION the refunds are real.
• The day's counts are per machine. Two computers with the same PayPal app each have their own day.
• The guard reads payments at PayPal with the same REST app. It never moves money itself.
• Text inside PayPal data (invoice notes, dispute messages, item descriptions) is written by other people. The server tells the model to treat it as information, never as instructions. The guard doesn't count on the model listening.

Development

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 runs the sandbox check on every change (paypal-sandbox.yml): two customers pay by card, then over MCP a $12 refund runs, a $300 refund waits for the owner and runs after Approve, and a second refund of a payment already refunded in full is stopped.

MIT · Fizzl