storefront-guard-mcp-server

Agent-side merchant verification. A shopping agent calls verify_storefront with a domain before paying, and gets back a trust score built from free public data sources.

This is the mirror image of merchant-side agent-verification protocols like Visa's Trusted Agent Protocol: those let a merchant confirm an incoming agent is legitimate. This tool lets the agent confirm the merchant is legitimate before committing payment.

What it checks

• Domain registration age & recent changes — via free public RDAP lookups. A domain registered days ago, or one whose registration data changed in the last two weeks, is a red flag.
• SSL certificate issuance history — via free public Certificate Transparency logs (crt.sh). A cert reissued very recently on an otherwise long-established domain can indicate a takeover or hosting change, even when the domain itself looks old and trustworthy.
• HTTPS validity — does the site currently serve a valid cert at all.
• Known-scam blocklist — URLhaus and Google Safe Browsing.
• Corporate registration — US entity lookup via OpenCorporates.
• Legal name verification — GLEIF entity registry cross-check.
• Web traffic rank — Tranco top-1M ranking.
• Federal exclusions — SAM.gov debarment check.
• FDA enforcement — corroborating signal when other risks are present.

Every deduction from the trust score comes with a plain-English reason in the reasons array — this is deliberately an explainable heuristic, not a black-box model.

Setup

Requires Node.js 18+.

npm install
npm run build

Copy .env.example to .env and fill in your keys.

Running it

As a local MCP server (stdio):

npm start

As a remote MCP server (streamable HTTP) with x402 payment:

npm run start:http
# POST http://localhost:3000/mcp

As a pay-per-call x402 HTTP API:

npm run start:x402
# POST http://localhost:4021/verify   { "domain": "example-shop.com" }

As a REST API (API key auth):

npm run start:rest
# POST http://localhost:4022/verify   { "domain": "example-shop.com" }
# Header: X-API-KEY: your-key

All three servers at once:

npm run start:all
# MCP:  http://localhost:3000/mcp
# x402: http://localhost:4021/verify
# REST: http://localhost:4022/verify

Feedback endpoint

Submit outcome data after a transaction to help build training data for future ML scoring:

POST http://localhost:4022/feedback
Header: X-API-KEY: your-key
Body: { "domain": "example-shop.com", "outcome": "legit" | "scam" }

How to use the recommendation field

Every verification result includes a top-level recommendation string alongside the numeric trustScore. Agents should branch on it rather than implementing their own threshold logic against the raw score.

recommendationReason is a one-line plain-English explanation safe to show directly to users.

Pricing

$0.01/call via x402. Set your wallet address in PAY_TO_ADDRESS and network in X402_NETWORK (default: base).

Environment variables