Botsrated MCP Server

BotsRated: MCP server

Signed checks of paid AI services, before your agent pays.

BotsRated measures paid AI-agent services with signed receipts. BotPulse is a separate digest and alerts product; these measurements do not claim coverage of every delivery outcome.

BotsRated publishes timestamped, receipt-backed measurements of paid x402 agent services on Base:

• unpaid probes: status, whether the 402 challenge is valid, latency, quoted vs listed price, and payTo;
• paid test-buys, each with its on-chain tx hash.

It reports facts and signed receipts only.

This repository documents the remote MCP server (nothing to install or run for it) and the optional Guard packages below.

Guard: check a payment before your agent signs it

Guard pairs with the x402 client your agent already pays with. It does not replace your agent runtime. Free. No key for local attach. It compares each payment request with BotsRated measurements and warns or blocks by your own rules. Facts and receipt links, not grades. Guard does not hold funds.

• Coding agents (Cursor, Claude Code, Cline, Codex): follow llms-install.md → When scaffolding x402 pay. The same recipe ships as a Cursor rule (.cursor/rules/botsrated-guard-attach.mdc) and an agent skill (docs/agent-skills/botsrated-guard-attach/SKILL.md). If a copy drifts, llms-install.md wins. Attaching Guard before the first paid request is a required step of that recipe, not an option.
• Routers and wallets: call Guard before pay with llms-install.md → Router or wallet: call Guard before pay (POST /v1/guard/check or MCP guard_check, spec in docs/guard/guard-check.md). The live route stays dark unless FEATURE_GUARD_CHECK=true. Optional, read-only, does not pay.
• How attaches are counted: outside Guard attaches that come back week over week, excluding internal calls. Not npm or PyPI downloads. See llms-install.md → How we count outside attaches. No public figure yet.
• Default path: hook → measured seller facts → your policy pass / fail receipt → Desk / alerts handoff. Canon: docs/guard/default-middleware.md.
• Per stack: integrations/README.md · live docs https://botsrated.com/docs/guard

Versions and the stacks not listed here (Google ADK, CrewAI, Pydantic AI, Mastra) are in integrations/README.md.

Tools

Facts bundle (preflight and check)

preflight (the MCP tool and GET /v1/preflight?url=<host>) returns measurements and receipt links. You set your own thresholds. The response is measurements and a receipt link.

check (paid, after the free daily quota) adds measured facts for one host and the last receipts. Those are still measurements and receipt links.

The payment guard in @botsrated/x402-preflight and botsrated keeps a smaller local bundle from this response (covered, host, knownPayTos / known_pay_tos, listingPayTo / listing_pay_to, observedNetwork / observed_network, observedAmount / observed_amount, stale, receiptUrl / receipt_url). Pick a named preset (warn, carefulBuyer, or dry-run-only) there. The guard does not invent a summary number from these fields.

Paid MCP tools: an unpaid call returns an x402 v2 PaymentRequired tool error (isError, structuredContent with accepts); an x402-aware MCP client (e.g. @x402/mcp) retries with the payment in _meta["x402/payment"]. The same data is on the HTTP routes, payable by any x402 client (e.g. @x402/fetch, Coinbase Agentic Wallet). All three paid routes are also listed in the Coinbase x402 Bazaar.

Free daily quota: the first 25 checks and 3 reports per client IP (IPv6 per /48) per UTC day are answered without payment; after that the normal x402 402 applies. /v1/find spends one check from that same quota. /v1/best has no free quota. Preflight stays free, no key, rate limits. No accounts, prepaid balances or stored credit. The badge is free and earned, never sold. Details: https://botsrated.com/pricing

Free HTTP endpoints and pages

Plans (seller alerts and data plans)

One x402 USDC payment on Base buys one 30-day period. There is no balance and no auto-renewal. Cancelling stops delivery. The dataset stays free.

Pro: watch up to 50 sellers or tools; alert to webhook, Slack, Discord or email. $19 / month by card + tax, or $29 / 30 days USDC. Tools you rely on (for example OpenAI, Anthropic, Gemini, Pinecone, Supabase) use those same 50 slots. No separate plan.

Paid BotPulse plans are retired; the feed stays free. Plans already bought keep working until their 30-day period ends. Free reads stay at https://botsrated.com/v1/botpulse/latest and https://botsrated.com/v1/botpulse/feed.json. Alerts on tools use Pro's 50 slots.

Subscribe with POST https://botsrated.com/v1/alerts/subscribe (free) or POST https://botsrated.com/v1/subscribe/{plan} (x402). The body and the webhook are checked before any 402. The webhook must answer the verification POST with the challenge; it must be https on a public DNS name, and redirects are not followed. Free alerts are email only: one confirmation link first, then plain-text alerts from alerts@botsrated.com. Slack, Discord, and webhook delivery need a paid plan (paid_channel_required on the free plan). Paid alert plans can use a signed webhook (Ed25519, botsrated-prober-1, see below, over {"m":"<timestamp>.<raw body>"}), a Slack incoming webhook or Discord channel webhook (plain text, not signed), or the same email path. Manage a subscription with GET /v1/subscription and POST /v1/subscription/{cancel,update} plus Authorization: Bearer <token>. Full details: https://botsrated.com/v1/plans

Install

Claude Code:

claude mcp add --transport http botsrated https://botsrated.com/mcp

Cursor / Windsurf / Cline / any client that takes a JSON config:

{
  "mcpServers": {
    "botsrated": { "type": "streamableHttp", "url": "https://botsrated.com/mcp" }
  }
}

VS Code (.vscode/mcp.json):

{ "servers": { "botsrated": { "type": "http", "url": "https://botsrated.com/mcp" } } }

Changelog

See CHANGELOG.md. Catalog listing copy (not submitted from this file): SUBMISSIONS.md.

Security

Report security issues privately: see SECURITY.md (botsrated@gmail.com, subject "Security"). Contributing: CONTRIBUTING.md.

Methodology, replies

• Methodology: https://botsrated.com/methodology
• A seller can send a reply about a measurement for free: https://botsrated.com/disputes (POST /v1/dispute). The measurement is re-checked and the reply is published next to the data. A measurement is a signed record, not a finding about the seller.
• Dataset signature: https://botsrated.com/dataset.sig.json. Key set: https://botsrated.com/.well-known/botsrated-key
• Receipt format v0.2.1 (draft; mcp_probe receipts for remote MCP servers; v0.2.1 updates reference schedules and MCP retention) and verifier: spec/SPEC.md. node spec/verify.mjs '<receipt.json|url>' needs verify.mjs, verify-core.mjs, and verify-node.mjs in one directory. verify.mjs alone does not run.
• Free: preflight, then the receipt link, then the signature check. x402 preflight puts it on latest_probe.receipt_url. MCP preflight puts it on servers[].latest_receipt_url (keep ?mcp=&day=&s=). CLI, single quotes: node spec/verify.mjs '<receipt_url>'. The pasted URL is a 20-hex id plus allowlisted host, mcp, day, and s only. A matching signature checks that record only. It is not a rating of the seller. The same check is importable as verifyReceipt from @botsrated/x402-preflight/verify-receipt (Node, offline; status signature valid, signature invalid, key unknown, or redacted copy). A copy with withheld_fields or withheld_note is redacted copy: not offline-verifiable, and not signature invalid. Check the stored record with GET /v1/verify. spec/receipt-page.mjs is that same check for Accept: text/html. It is not on the live host until Pages returns it (Content-Security-Policy header, and /spec/verify-browser.mjs plus /spec/verify-core.mjs). spec/courthouse/ is the same check as a folder you serve yourself.

Signing keys (Ed25519)

Raw 32-byte public keys, base64. Fingerprint = sha256 of the raw key bytes. A signature is valid for an object whose own timestamp (ts, or generated_at for snapshots) lies in [valid from, valid until). The live key set at /.well-known/botsrated-key is authoritative; this table is an out-of-band copy to compare against.

Payments are USDC on Base mainnet.