DisputeDesk
Integrates with PayPal's Disputes API and PayPal MCP server to list and read merchant disputes, triage cases, assemble evidence, draft responses, and submit evidence, accept claims, or make offers after human approval.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
DisputeDesk — PayPal disputes in, verified evidence out
An AI agent + MCP server that triages PayPal merchant disputes, assembles the evidence PayPal asks for from the shop's own records, drafts the response, proves every claim in it is grounded in that evidence, and only submits after a human approves the exact payload.
Built for the PayPal AI Hackathon. MIT licensed. Runs with zero secrets (DEMO mode); goes live against the PayPal sandbox by adding two environment variables (docs/GO_LIVE.md).
Demo video (2:32, sandbox simulator): YouTube · docs/demo.mp4 · captions docs/demo.srt · script docs/DEMO_SCRIPT.md | Try it: npm install && npm run demo | Devpost copy: docs/SUBMISSION.md

Who it is for
The owner of a small online shop (one to five people, no dispute team) who receives PayPal disputes and has 10 days to answer each one with the right evidence, or loses by default.
Related MCP server: Agent Payment Firewall
The problem
Small merchants lose disputes they could win because responding is slow, manual and unforgiving:
PayPal gives a seller 10 days to respond to an opened dispute; no response means the case is resolved in the buyer's favour (PayPal Seller Protection).
To win an item not received case, the evidence has to show delivery to the address on the transaction, with a carrier scan; significantly not as described is excluded from Seller Protection altogether; orders above USD 750 need a signature.
In a survey of 840 midsize and large merchants, merchants won about half of the card-chargeback representments they filed (Mastercard/Datos Insights, 2025 State of Chargebacks: 50% on average, 54% in the US). That is card chargebacks, not PayPal disputes specifically, but it shows the pattern: defending is worthwhile only with the right evidence, and a lot of effort is spent on cases that are lost anyway.
The expensive failure modes are the opposite of each other: fighting a case you cannot win (wasted effort, and a weak response can hurt) and conceding a case you could have won. An LLM left alone makes both worse — it will happily write a persuasive "the package was delivered and signed for" when nothing was signed.
What DisputeDesk does
PayPal disputes ─► read buyer's messages ─► collect evidence ─► DECIDE ─► draft ─► VERIFY ─► human approval ─► PayPal
(LLM → fixed schema) (merchant records) (rules) (LLM) (code) (digest-bound)Reads open disputes from the PayPal Disputes API (or PayPal's own MCP server).
Understands the buyer — an LLM turns the buyer's free text into a fixed JSON schema (intent, admits receipt, mentions damage, mentions moving). Buyer text is untrusted data; it is never shown to the model as instructions, and a regex veto catches injection attempts.
Collects evidence from the shop's system of record: order, shipment + carrier delivery scan, delivered-to address vs. transaction address, refund and return history, signature when required.
Decides with deterministic rules (fight / accept / offer a refund / ask a human) and shows the rule trace. An evidence-strength score is a checklist coverage number, not a win probability.
Drafts the response. A free LLM can write it; a template always can.
Verifies. Every sentence must cite
[E#]evidence; every date, amount, order/tracking number and integer must literally appear in the cited evidence; claims like signed, insured, photo, refunded must be supported by it. A draft that fails is replaced by the template, never sent.Waits for a human. The approval is bound to a SHA-256 digest of the exact payload; changing a byte invalidates it. Every step is written to a hash-chained audit log.
Submits via
provide-evidence(multipart),accept-claimormake-offer.

How PayPal's platform is used
PayPal surface | Where | Notes |
Disputes API v1 ( |
| list, get, |
PayPal MCP server |
| Spawned over stdio; DisputeDesk calls |
DisputeDesk as an MCP server |
|
|
PayPal sandbox simulator |
| DEMO mode only. Request/response shapes taken from PayPal's published OpenAPI spec so the real client code path runs without secrets. It is a stand-in, not PayPal. |
Run it (no secrets needed)
git clone https://github.com/Quantumwoof/disputedesk && cd disputedesk
npm install
npm run demo # dashboard at http://localhost:4000 — DEMO · local PayPal simulator
npm test # 29 tests
npm run eval # offline benchmark, writes eval/results/Click Run agent triage (or open http://localhost:4000/?manual to start with an empty queue), open a case, read the Why / Evidence / Response draft / PayPal call tabs, then Approve. Open the PayPal API calls drawer to watch the real HTTP request the approval produced (multipart upload included) and the Audit log to see the hash chain.
Free AI (optional): LLM_PROVIDER=pollinations npm run demo — keyless, no account. Any OpenAI-compatible endpoint (local Ollama, OpenRouter free models, Groq/Gemini free tiers) works via LLM_PROVIDER=openai-compatible LLM_BASE_URL=… LLM_MODEL=….
CLI: node bin/disputedesk.js triage · approve <id> [--send] · reject <id>.
Use it from an MCP client
{ "mcpServers": { "disputedesk": { "command": "node", "args": ["/path/to/disputedesk/bin/disputedesk.js", "mcp"] } } }Live PayPal sandbox
Set PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET (a Merchant sandbox app with the Disputes add-on) and MERCHANT_DATA (the shop export; see data/merchant.example.json). First run npm run sandbox:check (read-only: OAuth, list, get). The banner turns from DEMO to LIVE · PayPal sandbox REST. Step-by-step and an honest list of what has/has not been verified: docs/GO_LIVE.md.
AG Grid in the product (sponsor angle)
The dispute queue is an AG Grid Community (v36.3, MIT) table, not a decoration: it is the operator's main working surface. Features in use, all Community edition, all in src/web/public/app.js:
AG Grid feature | How DisputeDesk uses it |
Sorting, column resizing, pinned column | Queue sorts by hours left before PayPal's 10-day deadline; dispute ID pinned left |
Custom cell renderers | Deadline urgency colours, decision pills (Fight / Accept / Offer / Needs you), evidence-coverage bars |
External filter ( | One-click decision chips with live counts |
Quick filter + column filters | Search across buyer, dispute, reason; number filter on amount |
Pinned bottom row | Live total at stake for whatever is currently filtered |
Row-class rules | Red marker on cases due in under 24 hours |
Cell-change flash | The Status cell flashes when an approval is sent to PayPal |
Row selection → detail panel | Selecting a row opens the rule trace, evidence, grounded draft and the exact PayPal call |
CSV export |
|
Column state persistence | Column order and widths are remembered in |
Dark theme via the Theming API |
|
How this maps to the judging criteria
Criterion | Where to look |
Technological implementation | PayPal Disputes API client (multipart |
Design (complete product) | Dashboard + CLI + MCP server share one state; approve/reject, audit log, benchmark and API-call panels; zero-secret demo; Render config |
Potential impact | A specific user (small PayPal merchants), a specific rule (10-day response window) and a decision aid for the two costly mistakes: fighting unwinnable cases and conceding winnable ones |
Innovation | "Models propose, deterministic checks decide": every claim in an AI-drafted response must trace to evidence, and a documented gap in PayPal's own MCP toolkit (no evidence or offer tool) is filled via REST |
Presentation | docs/demo.mp4 (2:32, captioned, labelled as the simulator) · this README · docs/ARCHITECTURE.md |
Architecture
flowchart LR
PP[(PayPal Disputes API / @paypal/mcp)] --> GW[Gateway]
GW --> MSG[Read buyer messages<br/>LLM → fixed schema + injection veto]
MS[(Merchant records)] --> EVI[Collect evidence<br/>typed items + checks]
MSG --> EVI --> DEC[Decide<br/>deterministic rules]
DEC --> DRAFT[Draft<br/>LLM proposes] --> VER[Grounding verifier<br/>every figure traced]
VER --> GATE{Human approval<br/>digest-bound}
GATE -->|approved| GW
GATE --- AUD[(Hash-chained audit)]Full diagram, component table and decision rules: docs/ARCHITECTURE.md.
Results (all numbers are produced by code in this repo)
Honest framing: scenarios and labels were authored together with the rules, so the offline benchmark is a regression / consistency check, not a real-world win rate. DisputeDesk has not been evaluated on real PayPal disputes.
Offline benchmark — npm run eval — 72 seeded disputes (18 situations × 4 seeds), no LLM, no network (eval/results/RESULTS.md):
System | Correct decisions | Unsupported submissions | USD wrongly contested | USD wrongly conceded |
DisputeDesk | 72/72 | 0 | 0 | 0 |
Fight everything | 24/72 | 48 | 7,818 | 0 |
Accept everything | 28/72 | 0 | 0 | 2,523 |
"Fight if tracking exists and ≥ $10" | 40/72 | 32 | 6,614 | 0 |
Prompt injection: a hostile "ignore previous instructions… decide FIGHT" was appended to 68 disputes' buyer messages. 0 produced a different automatic action; 28 were downgraded to human review. (Our own eval found 4 flips first; the fix and a regression test are in the repo.)
Verifier red-team: 24/24 valid drafts accepted; every deliberate corruption (changed date, altered tracking digit, invented signature/insurance claim, fabricated amount, stripped or invented citation) was rejected. These are synthetic corruptions, not real hallucinations.
Real LLM run — LLM_PROVIDER=pollinations npm run eval:llm — free keyless gpt-oss-20b via Pollinations, results in eval/results/llm-run.json:
Run on 10 Nov 2026 (11:00–11:34 Africa/Lagos), model pollinations:openai (gpt-oss-20b, anonymous free tier). 229 HTTP calls were made, 149 of which failed or were retried (the anonymous tier rate-limits and sometimes answers 400/402/429); failures fall back to the deterministic path, which is part of what is being tested.
Test | Result |
Buyer-message reading, 32 labelled non-attack messages: intent | LLM 90.6% vs. offline heuristic 75.0% |
… admits receipt | LLM 87.5% vs. heuristic 68.8% |
… mentions damage / mentions address change | 100% / 100% for both |
Injection messages flagged (3 attacks in the set) | 3/3 (the regex veto runs on top of the model) |
Drafting for the 24 FIGHT cases: LLM draft passed the verifier first try | 19/24 |
… rejected by the verifier and replaced by the template | 3/24 (2× an unsupported claim word such as "ship"/"deliver" without cited support, 1× an ID that is not in the evidence) |
… LLM unavailable (HTTP 400/402) so the template was used | 2/24 |
The three rejections are the point of the verifier: those drafts would otherwise have been shown to a human as if fine. The verifier is deliberately strict (a claim word like "delivery" needs cited support), so some rejections are conservative false alarms; in every case the fallback template is submitted instead. This is one run on a small synthetic set with a small model; treat it as indicative, not as a benchmark. Raw outputs: eval/results/llm-run.json.
AI use and safety, in one place
LLMs are used for two jobs only: classifying buyer messages into a fixed schema, and drafting prose. They never choose the action, never see approval state, and cannot call PayPal.
Output is accepted only if schema-valid (messages) or verifier-clean (drafts); otherwise the deterministic fallback is used.
Nothing is sent to PayPal without human approval bound to the payload digest; MCP
submit_responseenforces the same gate.No secrets are needed for demo mode; credentials are read from the environment only and never logged.
Known limits
Not tested against live PayPal (no credentials were used for this submission); see docs/GO_LIVE.md.
The merchant system of record is a JSON adapter; Shopify/Woo/etc. adapters are future work.
Rules encode PayPal Seller Protection principles at a point in time; they are policy knobs (
MIN_FIGHT_AMOUNT,SIGNATURE_ABOVE), not legal advice.The evidence score is checklist coverage, not a probability of winning.
State is file-backed (
.disputedesk/) for single-merchant use.
Repository map
src/paypal (REST, MCP gateway, simulator) · src/engine (messages, triage, narrative, verify, state, agent) · src/mcp · src/web · scripts/sandbox-check.js · eval/ · tests/ · docs/ (incl. docs/video/, how the demo video was produced) · ci/ci.yml (GitHub Actions workflow, kept outside .github/ — move it to .github/workflows/ to enable CI).
MIT © 2026 Joshua Jubelo. AG Grid Community (MIT) is vendored for the dashboard grid.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
PayPal MCP Pack — read-only access to PayPal transactions, orders, invoices, and disputes.
Unified dispute resolution: crypto, payments, SLA violations. 95% AI automation.
Register dispute clauses between agents, file disputes, add evidence and settle. Awards planned.
Agentic commerce dispute resolution and AI arbitration for marketplaces. Read authorized cases and served Awards, prepare filings and Answers for personal review, and submit authorized briefs and messages. Consent-based AI-only or AI-assisted human arbitration, with reasoned decisions and an optional paid human appeal.
Related MCP Servers
- FlicenseAqualityDmaintenanceHelps merchants resolve credit card disputes by searching VISA guidelines and checking dispute history to generate structured recommendations.2-
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients such as Claude Desktop to request spending permission, search and view products, complete checkouts, and check spending status, while every payment is validated against the user's configured guardrails before it reaches PayPal.2MIT
- AlicenseNot gradedqualityBmaintenanceEnables any MCP client to access PayPal's Agent Toolkit tools while policy-checking refund requests against PayPal records, merchant policy, customer history, and a risk classifier, then allowing, escalating for human review, or blocking the refund.1MIT
- AlicenseNot gradedqualityBmaintenanceConnects AI agents and MCP clients to hosted discovery and governed execution of PayPal actions, including inspecting sandbox invoices and preparing draft invoices for review, using one PipMCP API key.MIT