Fairpay MCP server
Commit Nov 8, 2026Enables AI agents to manage milestone-based escrow payments on PayPal using an AI referee to verify work against acceptance criteria.
Also known as notaaaronfr/Fairpay
- Stars
- 3
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 8, 2026
- License
- MIT
What is Fairpay MCP?
Fairpay enables AI agents to manage milestone-based escrow payments on PayPal using an AI referee to verify work against acceptance criteria.
Summary generated from the project's README
About Fairpay MCP server
Fairpay enables AI agents to manage milestone-based escrow payments through PayPal by using an AI referee to verify work against specific acceptance criteria. This system solves the trust gap between freelancers and clients by ensuring money is only released when proof of work is provided. The server functions as a Model Context Protocol endpoint, providing tools like create_escrow, get_escrow, submit_work, release_payment, and request_changes to autonomous agents.
To use the service, a human must manually fund the escrow via a PayPal authorization link, as agents are restricted from approving payments. The AI referee, which can use K2 Horizon or Claude, evaluates submitted links to recommend full, partial, or no payment based on evidence. The setup requires PayPal credentials for real transactions, though a simulated mode is available for testing. Developers can deploy the system using Docker or run the built-in Cairn agent written in Rust to automate the hiring and settlement process.
What you can do with it
- 1Automated milestone creationAn AI agent can transform a single sentence describing a project into structured milestones with specific prices and criteria.
- 2Verifying freelance deliverablesThe AI referee reviews submitted work links to check if every requirement has been met before recommending a payout.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
ANTHROPIC_API_KEYK2_API_KEYPAYPAL_CLIENT_IDPAYPAL_CLIENT_SECRET
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablenotaaaronfr/fairpay is public and reachablegithub.com/notaaaronfr/fairpay ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-08github.com/notaaaronfr/fairpay ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubFairpay
Get paid for the work you did. Pay only for the work you got.
Milestone escrow on PayPal with an AI referee — and agents that can hire, but only pay on proof.
Live demo · Demo · How it works · Run it · For agents
Demo
Real run on the PayPal sandbox: the agent opens an escrow from one sentence → the referee checks the delivery criterion by criterion → the agent asks to pay, a person approves, and PayPal captures and pays out.
Why
Paying a stranger for work is a trust problem on both sides. Freelancers start without knowing they'll be paid; clients pay without knowing they'll get the work; and "done" was never written down in a way anyone can check. AI agents are now starting to buy services for people — nobody wants one that can send money with no proof and no limit.
How it works
| Step | What happens | PayPal | |
|---|---|---|---|
| 1 | Agree | Milestones, each with a price and acceptance criteria. AI turns "make it look good" into checks anyone can verify. | — |
| 2 | Fund | The client approves the total in PayPal. It's held, not taken — the freelancer can see the money exists. | Orders v2 · intent: AUTHORIZE |
| 3 | Prove | The freelancer submits a link. The AI referee reads it and marks every criterion met / partial / missing / can't verify, with evidence, then recommends what to release. | — |
| 4 | Pay | One click releases exactly that amount — captured from the hold and paid out. | Capture (final_capture: false) + Payouts |
| 5 | Settle | Whatever was never earned is voided back to the client. | Authorization void |
The referee recommends; it never pays. Money moves only on a person's click — and agents can never release more than the referee recommended.
On a logo-concepts delivery, the referee confirmed three bakery-themed concepts but noticed it couldn't open the six image files — so instead of guessing it recommended 50%, and told the freelancer exactly how to earn the rest. $60 was captured and paid out; $240 stayed held. On the final files it found every criterion met and recommended 100%. The sandbox trail is in docs/sandbox-evidence.md.
Screenshots
Run it
Requires Node 22.13+ (uses the built-in node:sqlite).
git clone https://github.com/notaaaronfr/Fairpay && cd Fairpay
npm install
npm run dev # http://localhost:3000
No keys needed. Without PayPal credentials PayPal runs simulated (ids start with SIM-, nothing moves); without an AI key an offline referee matches evidence by keyword. The footer always says which mode you're in.
For the real thing, create .env.local:
PAYPAL_CLIENT_ID=... # developer.paypal.com → Apps & Credentials → Sandbox
PAYPAL_CLIENT_SECRET=...
K2_API_KEY=... # K2 Horizon (IFM) — free, tried first
ANTHROPIC_API_KEY=... # Claude — the fallback
Build the agent once (needs Rust): npm run agent:build.
- New → type a sentence in Describe it (or use the prefilled builder) → create.
- Fund → approve with a PayPal sandbox Personal account. The escrow shows the amount held.
- Click the avatar (top right) to switch to FR (freelancer) → submit a milestone with a public link and a note → read the referee's verdict.
- Switch back to CL (client) → Release, or Settle with agent and Approve the payment it asks for.
- Return the rest when you're done — it's voided in PayPal.
For agents
POST /api/mcp is a Model Context Protocol server (streamable HTTP) with five tools: create_escrow, get_escrow, submit_work, release_payment, request_changes.
The guardrails live on the server, not in the agent's prompt:
- A human funds.
create_escrowreturns PayPal's approval link — an agent can't approve a payment. - No paying beyond the evidence. An agent can release at most what the referee recommended.
- Paying is destructive.
release_paymentcarriesdestructiveHint: true, so frameworks that honour MCP annotations pause for approval. - Spend limits. Paid AI calls are capped per visitor and per day;
FAIRPAY_AGENT_KEYcan require a bearer token.
curl -s http://187.126.26.84:8790/api/mcp -H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
The built-in agent, on Cairn
Fairpay ships its own agent in agents/cairn-buyer, built on Cairn (Rust). In the app, Describe it turns one sentence into milestones, criteria and prices; Settle with agent pays what the referee supports and pauses every payment for an Approve / Deny card — the run resumes from Cairn's journal in a fresh process. It runs on K2 Horizon for free, with Claude as the fallback, under a Cairn budget.
cd agents/cairn-buyer
cargo run --release -- hire "A logo for my bakery, two milestones, \$300, pay lina@example.com"
cargo run --release -- settle ctr_xxxxxxxx # asks you y/N before every payment
Under the hood
app/ Next.js 16 (App Router, server actions)
page.tsx dashboard
new/ agent brief + escrow builder
c/[id]/ the escrow: tracker, milestones, verdicts, agent, record
c/[id]/paypal/ PayPal return URL → authorize the hold
activity/ the record, across escrows
api/mcp/ MCP server for agents
lib/
paypal.ts Orders (authorize), capture, Payouts, void; simulated mode
referee.ts AI referee + criteria sharpener (K2 → Claude, structured JSON)
escrow.ts the flow and its rules
agent.ts bridge to the Cairn agent (runs, approvals, journal)
limits.ts spend limits for paid AI calls
db.ts SQLite — contracts, milestones, events, agent runs
agents/cairn-buyer/ the built-in agent (Rust, Cairn)
deploy/compose.yml isolated Docker deploy · render.yaml for Render
test/ node:test — escrow rules, PayPal requests, MCP guardrails, limits
PayPal, precisely
- Hold —
POST /v2/checkout/orders(intent: AUTHORIZE), then/authorizewhen the client returns. - Release —
POST /v2/payments/authorizations/{id}/capturefor exactly the milestone amount (final_capture: false), thenPOST /v1/payments/payoutsto the freelancer's PayPal email. - Settle —
POST /v2/payments/authorizations/{id}/voidreturns what was never released. - Every call carries a
PayPal-Request-Idderived from the escrow or milestone, so a retry or double click can't capture or pay twice.
The AI referee
- One structured call per submission: per-criterion status + evidence, a recommendation (
release/partial/request_changes), a percentage, a note for the freelancer, a confidence. - K2 Horizon first (free), Claude Opus 5.5 as the fallback, an offline referee when neither is configured.
- Reads the delivered link (a GitHub repo is read as its README), refuses private and local addresses, and treats submission text as evidence, never instructions. Output is clamped to its own rules before anyone sees it.
Deploy
cp .env.example deploy/.env # keys, FAIRPAY_BASE_URL, FAIRPAY_PORT
docker compose -f deploy/compose.yml --env-file deploy/.env up -d --build
One image builds the app and the Cairn agent. The compose project is isolated (own network, volume and port), runs as a non-root user and is CPU- and memory-capped, so it can share a server safely. render.yaml deploys the same image on Render.
Tests
npm test
19 tests: contract validation · funding holds the full total · no work before funding · referee-driven and partial releases · never paying twice · closing returns exactly the remainder · offline-referee honesty · URL safety · the exact requests PayPal receives · MCP guardrails (agents can't fund, can't over-pay) · spend limits.
Built with
Next.js 16 · React 19 · TypeScript · Node node:sqlite · Motion · PayPal Orders, Payouts & Authorizations (sandbox) · K2 Horizon (IFM) · Claude Opus 5.5 · Model Context Protocol · Cairn (Rust) · Docker. The demo video was made with Playwright, Piper TTS and ffmpeg (scripts/video).
Built for the PayPal AI Hackathon 2026. MIT.
Fairpay MCP questions
Can an AI agent fund an escrow on its own?
No, a human must fund the escrow. The create_escrow tool returns a PayPal approval link that an agent cannot bypass.
How does the AI referee ensure agents don't overpay?
The server enforces guardrails where an agent can only release the specific amount recommended by the AI referee based on the evidence provided.
What happens to the money that is not earned?
Any funds that were held but never earned through completed milestones are voided back to the client.
Does the server require API keys to run?
It can run without keys in a simulated mode, but real PayPal and AI functionality requires specific environment variables.