PayPal Operations Agent

AI triage for PayPal disputes and unpaid invoices: an MCP server for Claude, a deadline console, and reminders that need human approval and are sent exactly once.

Comment

Inspiration

Small businesses on PayPal quietly lose money in two places: disputes that expire before anyone answers, and unpaid invoices nobody follows up on. We wanted an AI assistant that watches both and does the tedious triage, while authorization for anything that reaches a customer stays with a person.

What it does

  • Reads PayPal: lists open disputes and unpaid invoices through the official PayPal REST APIs (sandbox).
  • Works with AI assistants through MCP: an MCP server exposes six tools (list disputes, list unpaid invoices, explain an invoice's priority, read reminder history, propose a reminder, execute an approved reminder), so Claude or any MCP-capable assistant can triage and draft the next action in conversation.
  • Explains why an invoice comes first: for a supplied queue, the priority tool returns the invoice's position with the evidence behind it (deadline, outstanding amount, previous reminders, open dispute) and compares it with plain deadline-only sorting, plus a draft for the AI client to rewrite. It reads no PayPal data on its own and approves nothing.
  • Shows what happened to a reminder: the history tool returns proposal, approval, execution attempt and result in order, and marks missing or unconfirmed results as uncertain instead of guessing.
  • Keeps humans in charge: a reminder proposal authorizes nothing. The operator reviews the exact proposal in a separate terminal and approves it for 15 minutes. Any change invalidates the approval, and the MCP server has no approval tool, so the AI can never approve its own request.
  • Sends exactly once: the executor records an attempt before calling PayPal, so a retry, a crash or a concurrent request cannot send the same reminder twice. Uncertain outcomes require reconciliation, not a blind retry.
  • Verified webhooks: every PayPal webhook is verified with PayPal's verify-webhook-signature API before it is stored, and duplicate deliveries are ignored.
  • Operations console: an AG Grid console sorts disputes and invoices by deadline with type and due-date filters. It runs locally with fictional records, and the AI explanations shown there are simulated. A read-only sandbox view reads sandbox unpaid invoices and the local proposal history.

How we built it

TypeScript and Node.js, SQLite, the Model Context Protocol SDK, AG Grid Community, and the PayPal REST APIs for OAuth, Disputes, Invoicing and Webhooks, all in the PayPal sandbox. GitHub Actions runs the build and 105 automated tests on every push.

AI tools used

  • Claude / any MCP client is the conversational operator: it calls the MCP tools to read PayPal data, rank what is urgent and draft reminder proposals. Approval stays outside the AI by design.
  • AI coding agents (an autonomous OpenAI Codex-based agent and Claude Code) helped write the code, tests, debugging and documentation. Every claim on this page was verified against the PayPal sandbox.

Validation in the PayPal sandbox (25 and 26 October 2026)

  • A real MCP client read disputes and unpaid invoices through the official APIs.
  • An operator approved a reminder for a fictional invoice in the terminal, and the MCP executor sent it exactly once; the invoice was read back with HTTP 200.
  • A genuine PayPal webhook (INVOICING.INVOICE.CREATED for a fictional draft invoice) reached the public receiver, was verified with PayPal and stored once; a redelivery of the same event was answered and ignored as a duplicate.
  • 56 of 56 automated tests passed at the time of the live run; after adding priority explanations, reminder history and reconciliation the suite has 105 tests, all passing on Linux CI. No real customer or payment was involved.

Challenges we ran into

Separating an assistant's suggestion from a person's authorization; keeping approvals valid across restarts; handling ambiguous network outcomes without duplicate reminders; and a real-world one during webhook validation: the receiver first answered 503 because its system service lacked the host's outbound proxy settings, so it could not reach PayPal to verify signatures. After fixing that, the signed event was verified and stored.

Accomplishments that we're proud of

An AI-facing integration where the safety rails are enforced by the server, not by the prompt, and every step was proven live in the PayPal sandbox.

What we learned

Useful automation needs a hard boundary between drafting and authorizing. Recording an attempt before an external call makes uncertain outcomes explicit. And webhook validation must include a genuine delivery and a redelivery.

What's next

Dispute responses prepared for human review, more reminder channels, and feedback from real operators on the triage order.

Try it

Judges: start with the 5-minute document review at the top of JUDGES.md (no installation). It includes a fictional example where the priority tool reorders four overdue invoices against plain due-date order, with the recorded inputs and outputs. The 10-minute walkthrough without PayPal credentials (fictional console and the full test suite) follows in the same file: https://github.com/martinPisacreta/paypal-ops-agent/blob/main/JUDGES.md

Repository with setup and run instructions: https://github.com/martinPisacreta/paypal-ops-agent

Built With

Share this project:

Updates

Submission history