Fairplug MCP server
Commit Oct 17, 2026Allows AI assistants to surface sponsored offers with tracked links and mandatory disclosure text to ensure honest monetization.
Also known as fairplug/fairplug-mcp, fairplug-mcp
- Stars
- 0
- Tools
- 2
- Downloads, 30 days
- —
- Latest version
- 0.1.0
- Last commit
- Oct 17, 2026
- License
- MIT
What is Fairplug MCP?
Fairplug allows AI assistants to surface sponsored offers with tracked links and mandatory disclosure text to ensure honest monetization. It exposes 2 tools, such as search_offers, get_tracked_link.
Summary generated from the project's README
About Fairplug MCP server
Fairplug provides a framework for AI assistants to present sponsored offers while maintaining transparency through mandatory disclosure text. This server is designed for developers building agents that want to monetize interactions honestly by ensuring users always recognize when content is promoted. The current sandbox version uses fictional data and does not involve real money or live advertisers, making it an ideal environment for testing integrations.
Developers can connect via a streamable HTTP setup or use npx mcp-remote for stdio-only clients. The server includes tools like search_offers to find products by category or region and get_tracked_link to generate HMAC-signed URLs with a 15-minute expiration. While the sandbox is public and requires no authentication, a production deployment requires bearer tokens for security and environment variables for signing secrets and admin access.
What you can do with it
- 1Monitor agent earningsBuilders can use administrative tools to generate reports on clicks, conversions, and net payouts.
Written from the project's README. Every use case is checked against a quote from it.
How to install Fairplug MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Fairplug MCP in Claude Code
$ claude mcp add --transport http fairplug-mcp https://fairplug-mcp.fairplughq.workers.dev/sandbox/mcpInstall Fairplug MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"fairplug-mcp": {
"url": "https://fairplug-mcp.fairplughq.workers.dev/sandbox/mcp"
}
}
}Install Fairplug MCP in VS Code
.vscode/mcp.json
{
"servers": {
"fairplug-mcp": {
"type": "http",
"url": "https://fairplug-mcp.fairplughq.workers.dev/sandbox/mcp"
}
}
}Install Fairplug MCP in VS Code CLI
$ code --add-mcp '{"name":"fairplug-mcp","type":"http","url":"https://fairplug-mcp.fairplughq.workers.dev/sandbox/mcp"}'Install Fairplug MCP in Codex
$ codex mcp add fairplug-mcp --url https://fairplug-mcp.fairplughq.workers.dev/sandbox/mcpInstall Fairplug MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.fairplug-mcp] url = "https://fairplug-mcp.fairplughq.workers.dev/sandbox/mcp"
Install Fairplug MCP in Gemini CLI
$ gemini mcp add -s user --transport http fairplug-mcp https://fairplug-mcp.fairplughq.workers.dev/sandbox/mcpInstall Fairplug MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"fairplug-mcp": {
"url": "https://fairplug-mcp.fairplughq.workers.dev/sandbox/mcp",
"type": "http"
}
}
}Fairplug MCP tools 2
Detected from the READMEsearch_offersget_tracked_link
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 reachablefairplug/fairplug-mcp is public and reachablegithub.com/fairplug/fairplug-mcp ↗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-10-17github.com/fairplug/fairplug-mcp ↗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 model2 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeinitialize answered with protocol 2025-06-18 in 297 msPass
README
View on GitHubFairplug 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 -- <base-url> - (sandbox only) or <base-url> <mcp-token> <admin-token> (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 hassponsored: true, a disclosure label and sponsor name.get_tracked_link(offer_id, agent_id, context?): returns a tracked URL (HMAC-signed, 15-min TTL) and a requireddisclosure_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. Example disclosure_text: "Sponsored: is promoted by . Fairplug may earn a commission if you buy through this link."
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/mcpis separate, stores nothing and exposes no report/admin data.- Never commit secrets. Set
FAIRPLUG_SIGNING_SECRET,FAIRPLUG_MCP_TOKEN,FAIRPLUG_ADMIN_TOKENas environment variables orwrangler 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 FAIRPLUG_DATA_DIR). 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
record_conversion 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 '<tracked_url>'). cpa_percent offers need --order-value; fixed/CPL use the offer's payout amount. Re-recording for the same click replaces its status (e.g. reversed).
Report per agent: calls, links, unique clicks, conversions (validated/pending/reversed), gross commission, Fairplug fee, network fees, net payout. Only validated conversions count toward money. Fee = 10% of validated commission, US$0.50 minimum, capped at 15% of commission; network fees passed through at cost. Net = gross - fee - network fees.
Small-commission rule: the 15% cap overrides the US$0.50 minimum. The minimum would exceed the cap for any commission under ~US$3.33 (0.50 / 0.15), so there the fee is floor(15% x commission). Examples: US$2.00 commission -> fee US$0.30 (not 0.50); US$1.00 -> 0.15; US$3.00 -> 0.45; US$4.00 -> 0.50 (minimum applies from ~US$3.34 up to US$5.00, where 10% takes over). Implemented in src/fees.ts, covered by test/core.test.ts. Assumed interpretation; confirm.
Known limits / not implemented
- Fee edge case: see "Small-commission rule" above (cap beats minimum; assumed, confirm).
- No FX: non-USD payouts in the seed (NZD) are treated as USD-equivalent in the report.
- Signing secret defaults to a public dev value; set
FAIRPLUG_SIGNING_SECRETfor anything beyond local use. - Not built: disclosure_rendered receipts (D5), auction/ranking scores, rate limits, API keys, ledger/reserves, validation windows, real network/postback integration, real-money ledger; the hosted conversion endpoint is an admin-recorded simulation, not a real network postback, bot/IP filters. Search is simple keyword scoring, not BM25/embeddings.
- The stdio setup's redirect server only binds to 127.0.0.1; use the HTTP/remote build below for links that work off-machine.
Remote (streamable HTTP)
One process/Worker serves POST /mcp (MCP streamable HTTP, stateless, JSON responses), GET /r/clk_... (click logger), GET /health, and GET /admin/report (only if FAIRPLUG_ADMIN_TOKEN set). Shared code: src/handler.ts (Web Request -> Response).
Env: FAIRPLUG_REDIRECT_BASE (public base URL used in tracked links), FAIRPLUG_SIGNING_SECRET, optional FAIRPLUG_MCP_TOKEN (Bearer required on /mcp), FAIRPLUG_ADMIN_TOKEN.
Node (any host/VM/container): FAIRPLUG_REDIRECT_BASE=http://127.0.0.1:8788 npm run start:http (PORT / FAIRPLUG_PORT, default 8788). Events go to var/events.jsonl.
Cloudflare Workers (recommended free host): worker/index.ts + wrangler.jsonc. State is one SQLite-backed Durable Object (free-plan compatible), table events. Local test, no account needed (wrangler needs Node >= 22):
printf 'FAIRPLUG_SIGNING_SECRET=dev\nFAIRPLUG_MCP_TOKEN=test-token\nFAIRPLUG_ADMIN_TOKEN=admin-token\n' > .dev.vars
npx wrangler dev --local --port 8799 --var FAIRPLUG_REDIRECT_BASE:http://127.0.0.1:8799
npm run build && npm run remote-check -- http://127.0.0.1:8799 test-token admin-token
Client config for builders: { "mcpServers": { "fairplug": { "url": "https://<host>/mcp", "headers": { "Authorization": "Bearer <token>" } } } } (or npx mcp-remote https://<host>/mcp --header "Authorization: Bearer <token>" for stdio-only clients).
Open-books endpoints (hosted + Node build)
All money is USD, 2 decimals. ADMIN = Authorization: Bearer <FAIRPLUG_ADMIN_TOKEN>. Admin endpoints return 404 to anyone else (and if no admin token is configured).
POST /admin/agent-token(ADMIN) body{"agent_id":"my_agent"}->{agent_id, token}. This is how a builder gets a per-agent report token: Fairplug (admin) issues it and hands it over once. Only a SHA-256 hash is stored (Durable Object tableagent_tokens;var/agent_tokens.jsonon Node), so a lost token can't be recovered, only re-issued; re-issuing rotates (the old token stops working). The token only grantsGET /reportfor that one agent_id.POST /admin/conversion(ADMIN) body{"click_id":"clk_...","status":"validated|pending|reversed","commission":20.00,"network_fee":0.25,"order_value":189.00}(statusdefaults to validated,network_fee/order_valueoptional). The click_id must have an issued link and a recorded click. Re-posting for the same click_id replaces its status (e.g. validated -> reversed). Simulation stand-in for a network postback.GET /report?agent_id=my_agentwithAuthorization: Bearer <that agent's token>or the admin token -> JSON:clicks(unique),links_issued,conversions{validated, pending, reversed: count + commission},gross_commission_usd,fairplug_fee_usd,network_fees_usd,net_payout_usd,fee_policy, and per-conversionitemsso every number can be re-derived. Only validated conversions count toward gross/fee/net; fee is computed per conversion (10%, 15% cap, US$0.50 min, cap wins for tiny commissions); network fees at cost.
curl -X POST $HOST/admin/agent-token -H "Authorization: Bearer $ADMIN" -H 'content-type: application/json' -d '{"agent_id":"my_agent"}'
curl -X POST $HOST/admin/conversion -H "Authorization: Bearer $ADMIN" -H 'content-type: application/json' -d '{"click_id":"clk_...","commission":20,"network_fee":0.25}'
curl "$HOST/report?agent_id=my_agent" -H "Authorization: Bearer $AGENT_TOKEN"
Tests: test/http.test.ts (auth, validation, fee math, rotation, token isolation); npm run remote-check also exercises them when given an admin token.
Deploy (Cloudflare)
- Free Cloudflare account (email only, no card).
npx wrangler login(Node >= 22). - Edit
FAIRPLUG_REDIRECT_BASEinwrangler.jsonctohttps://fairplug-mcp.<your-subdomain>.workers.dev. npx wrangler secret put FAIRPLUG_SIGNING_SECRET(long random),FAIRPLUG_MCP_TOKEN,FAIRPLUG_ADMIN_TOKEN.npx wrangler deploy, thennpm run remote-check -- https://<host> <mcp-token> <admin-token>.- Do not add a payment method / Workers Paid; on Free, going over limits just fails requests, nothing is billed. Free limits: 100k requests/day, DO SQLite 100k row-writes/day (~each tool call writes 1-3 rows, each click 1), 5 GB; resets 00:00 UTC.
Fairplug MCP questions
How do I add Fairplug MCP to Claude Code?
Run claude mcp add --transport http fairplug-mcp https://fairplug-mcp.fairplughq.workers.dev/sandbox/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Fairplug MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Fairplug MCP provide?
It exposes 2 tools, including search_offers, get_tracked_link.
Is the current version of Fairplug live?
No, it is currently in an early pilot stage using fictional example data and simulated conversions.
How does the disclosure requirement work?
Every sponsored offer must be labeled with specific disclosure text returned by the server to ensure users know it is promoted.
What are the fees for using Fairplug?
Fairplug takes 10% of a validated commission, with a US$0.50 minimum, but this is capped at 15% of the commission for very small amounts.
Can I try the server without signing up?
Yes, there is a public, read-only sandbox available that uses fictional data and requires no signup or API key.