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. Paid BotPulse plans are retired; the feed stays free. These measurements do not claim coverage of every delivery outcome.

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

• 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). This route and the MCP guard_check tool are not live on botsrated.com yet. 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

Stack	Install	Attach
LangChain	pip install langchain-botsrated	README
OpenAI Agents SDK	pip install botsrated-openai-agents	README
LangGraph	pip install langgraph-botsrated	README
Llama Stack	pip install llama-stack-botsrated	README
LlamaIndex	pip install llama-index-tools-botsrated	README
Microsoft Agent Framework	pip install agent-framework-botsrated	README
Vercel AI SDK	npm install @botsrated/ai-sdk	README
Any Python x402 client	pip install "botsrated[x402]"	README
Any TypeScript x402 / MCP client	npm install @botsrated/x402-preflight	README

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

MCP endpoint	https://botsrated.com/mcp (Streamable HTTP, JSON responses, no auth)
Official MCP Registry	com.botsrated/botsrated
Website	https://botsrated.com
OpenAPI	https://botsrated.com/openapi.json
A2A agent card	https://botsrated.com/.well-known/agent-card.json
llms.txt	https://botsrated.com/llms.txt
Contact	botsrated@gmail.com

Tools

Live MCP tools/list at https://botsrated.com/mcp has 12 tools:

Tool	Price	What it returns
preflight	free, no key, rate limits	Facts bundle for an x402 seller or remote MCP server (host or URL): latest unpaid probe, freshness, directory listing, receipt link. Measurements and a receipt link. See below
check_mcp_setup	free	Check the MCP servers in a config or a list of hosts (up to 50 hosts or an mcp.json). Same report as POST /v1/dependency-watch/report
watch_free	free	Email when a covered host's measured facts change (1 host, at most once per UTC day, 30 days, up to 3 active watches per client). Same watch as POST /v1/alerts/subscribe
what_changed	free	Measured changes for a free watch. Pass the handle from watch_free
find	free (uses 1 of the 25 free checks per client IP per UTC day)	Top matching x402 sellers and remote MCP servers for a need (q, e.g. weather), each with a one-line factual reason and its page URL. Same filters as best, without the full ranking. HTTP: GET https://botsrated.com/v1/find?q=
coverage	free	How many x402 sellers and MCP servers are covered, from which sources, and when the last probe ran. Live counts: GET https://botsrated.com/v1/coverage
sample	free	A real sample of a paid answer (check, report or best) for a fixed example
check	$0.01 (x402, USDC on Base); first 25 per client IP per UTC day free on this tool and on HTTP GET /v1/check (one shared quota)	Measured facts and the last 5 receipts for one host. Paid at GET https://botsrated.com/v1/check?host=
report	$0.002 (x402); paid on MCP from the first call. The first 3 reports per client IP per UTC day are free only on HTTP GET /v1/report/{host}	Full receipt history for one host. Paid at GET https://botsrated.com/v1/report/{host}
best	$0.01 (x402); paid on MCP from the first call; no free quota	Top 3 measured providers for a task (sort=reliability|price|latency). Paid at GET https://botsrated.com/v1/best?task=
seller_self_check	free	Stored measurements for a host anyone can read: listing versus quoted price and recent unpaid probes
seller_announce	free (verified owner)	Verified owner posts a planned price and/or payTo

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.

Field	What you get back
found, host	Whether this host is in the probe record, and the host name
latest_probe	Latest unpaid probe: ts, status, valid_402, latency_ms, observed amount (live_amount), observed payTo (live_payTo), live_network
latest_probe.receipt_url	Link to the signed receipt for that probe (https://botsrated.com/receipt/...). The receipt is the record
freshness	last_probe_at, age_seconds, stale (older than 24 h)
listing	Directory price and payTo. Directory data is not a probe observation
recent_window	Probe count, how many returned a valid 402, latency. A count in a window
note	Facts only

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 per client IP (IPv6 per /48) per UTC day are free on the MCP check tool and on HTTP GET /v1/check (one shared quota). The first 3 reports per client IP per UTC day are free only on HTTP GET /v1/report/{host}. MCP report and best are paid from the first call. /v1/find spends one check from the shared check quota. /v1/best has no free quota. After the free quota the normal x402 402 applies. 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

GET https://botsrated.com/v1/find?q=<need>	Top matches for a need with a reason (uses 1 of the 25 free checks per client IP per UTC day, shared with /v1/check)
GET https://botsrated.com/v1/pulse	Live totals (cached 60 s): services watched, working in the last 24 h, down or failed in 7 days, checks run in 7 days. Never names a seller
GET https://botsrated.com/v1/savings-rates	Measured rates (offline, payTo changes, price vs listing) with sample size, dates and source
https://botsrated.com/sellers	Browse and filter every covered seller and MCP server
https://botsrated.com/s/<host>	One page per seller or MCP server: status, 30-day chart, price, payTo, test purchases, receipts, alternatives
https://botsrated.com/savings	What we check for, with the rates we measured
https://botsrated.com/leaderboard	Data table of the top 300 covered x402 sellers

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 $19 / 30 days USDC. Tools you rely on (for example OpenAI, Anthropic, Gemini, Pinecone, Supabase) use those same 50 slots. No separate plan.

Plan	Price per 30 days	What you get
alerts-free	$0	Watch 1 seller. Daily digest: one email per UTC day when its facts change. Slack, Discord, and webhook need a paid plan (paid_channel_required). Up to 3 free alerts per client IP, 1,000 in total
alerts-50 (Pro)	$19	Up to 50 sellers or tools; a signed webhook within one probe cycle of a change (payTo, quoted price, valid 402, listing, freshness)
desk-pro (Desk Pro; API name data-pro)	$199	Bearer token for /v1/check, /v1/report, /v1/best without per-call payment (600 requests/min), the change-event export (GET /v1/export/changes.ndjson?host=), and the team workspace
Data licensing	No public price	Volume or bulk delivery; support terms agreed per contract: botsrated@gmail.com

data-starter is not on sale; a token already issued keeps working until it expires. Card plans: Desk Team $99/month, Desk Pro $199/month, Pilot $149 for 6 weeks (paid once). Current prices: https://botsrated.com/pricing

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 live on the host (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.

key_id	Status	Valid from (UTC)	Valid until (UTC)	Signs	Public key	sha256 fingerprint
botsrated-prod-1	active	2026-10-23T15:00:00Z	2027-10-23T00:00:00Z	dataset snapshots, paid test-buy receipts	oTK25Dq3wU2+apPYddiv4T+8is2s3hL1k6ozjMAbEWQ=	ac58fa77b9f6a26805efb65d331d6d77da3dfbdbbe981cc7510692852a50e74a
botsrated-prober-1	active	2026-10-23T12:00:00Z	(none)	cron probe receipts, daily aggregates, archive manifests	G5aD8mz2rkbpLPQuEC2t50AaJpMjGcflTXuRmeJETsE=	805e75f8795ff38c4805653962ba75991fc8bdcaef3f80441e0775e405a3a628
botsrated-staging-1	retired (verify only)	2026-10-22T00:00:00Z	2026-10-23T15:00:00Z	dataset snapshots generated before 2026-10-23T15:00:00Z	OfGrLtyJYCC1K9jjhvq0Zduwgqq68DvzR1StOo5ZpO0=	71db9690ef765ce6b923d63fc71e1a65474e87ee1073532eafb9099b1e6f0288

Payments are USDC on Base mainnet.