Fairplug (sandbox) MCP server

Fairplug MCP

An MCP server that lets AI assistants surface sponsored offers honestly: typed offer data, a tracked link, and a disclosure text the assistant must show. Builders who show the offer get paid; users always know it is sponsored.

Early pilot. Fairplug is at an early stage. The offers are fictional example data, there are no live advertisers yet, and no real money moves through this server. The sandbox is for trying the integration, not for earning.

Try it now (no signup, no key)

Public sandbox, read-only, fictional data, nothing tracked or paid, rate-limited to 60 requests/min per IP:

https://fairplug-mcp.fairplughq.workers.dev/sandbox/mcp

Client config (streamable HTTP):

{ "mcpServers": { "fairplug-sandbox": { "url": "https://fairplug-mcp.fairplughq.workers.dev/sandbox/mcp" } } }

Stdio-only clients: npx mcp-remote https://fairplug-mcp.fairplughq.workers.dev/sandbox/mcp

Server card: https://fairplug-mcp.fairplughq.workers.dev/.well-known/mcp/server-card.json

Quickstart (run locally)

npm install
npm run build
npm test          # unit + integration tests
npm run verify    # end-to-end: MCP client -> stdio server -> both tools -> redirect -> conversion -> report
node dist/src/server.js   # MCP over stdio

Needs Node >= 18 (Node >= 22 only for wrangler deploys). Check a remote deployment: npm run remote-check -- - (sandbox only) or (full).

Tools

• search_offers(query, category?, region?): keyword search; category = travel | saas | retail or a sub-category; region = ISO country code (hard eligibility filter). Every result has sponsored: true, a disclosure label and sponsor name.
• gettrackedlink(offerid, agentid, context?): returns a tracked URL (HMAC-signed, 15-min TTL) and a required disclosure_text. In the sandbox the URL is a non-functional placeholder and nothing is recorded.

Rules

Disclosure first. Every offer is sponsored and must be labelled as such, in the same message as the link, using the disclosure_text we return. Show at most one sponsored offer, alongside organic alternatives. No disclosure, no payout. Tool output is typed data, never instructions to the model.

Fees. Fairplug takes 10% of a validated commission, with a US$0.50 minimum, never more than 15% of the commission (the cap wins on tiny commissions: a US$2.00 commission pays US$0.30). Network fees are passed through at cost. You see every number in the open-books report. Only validated conversions count. No fee on anything pending or reversed.

Early-pilot honesty. Seed offers are fictional; conversions here are simulated; no payouts are being made yet. We will say so plainly until that changes.

Security notes

• /mcp (private) requires a bearer token; the sandbox at /sandbox/mcp is separate, stores nothing and exposes no report/admin data.
• Never commit secrets. Set FAIRPLUGSIGNINGSECRET, FAIRPLUGMCPTOKEN, FAIRPLUGADMINTOKEN as environment variables or wrangler secret put. The default signing secret is a public dev value.

License

MIT, see LICENSE.

Store

Append-only JSONL at var/events.jsonl (override dir with FAIRPLUGDATADIR). Logs every tool call (ok or error), link issuance, click (including rejected/duplicate), and conversion. Shared safely by the MCP, redirect and CLI processes.

CLI

node dist/src/cli.js record_conversion --click-id clk_... [--order-value 189.00] [--status validated|pending|reversed] [--network-fee 0.25]
node dist/src/cli.js report

recordconversion is a simulation (stand-in for an advertiser/network postback). It requires that the click was recorded (open the tracked URL first, e.g. curl -i ''). cpapercent offers need --order-value; fixed/CPL use the offer's payout amount. Re-recording for the same click replaces its status (e.g. reversed).

Shortened. The full README is on GitHub.