Scout Packs MCP Server

Scout Packs — Tiger Operations

Verified B2B lead packs and per-lead enrichment lookups sold to AI agents over x402 (USDC on Base, eip155:8453). Demand-probe pricing (2026-10-04): $0.01 per lookup or pack. Margin inversion vs. Scout COGS is acknowledged — this is a demand probe, not a business model. Kill gate: ≥3 paid lookups from ≥2 distinct wallets in 7 days post-reprice.

Per-lead enrichment: GET /lookup?query=<company or domain> — 402 paywall, $0.01 USDC, POST /fulfill-lookup returns one verified business email + source URL + provenance.

Each lead: company_name, city_state, category, contact_email (verified business email), source_url.

Endpoints

• GET / — human landing page
• GET /catalog — packs & prices (JSON)
• GET /.well-known/x402 — machine-readable payment terms
• GET /llms.txt — agent buying instructions
• GET /packs/{25,50,100}/preview — redacted preview (emails masked), free
• GET /packs/{25,50,100} — 402 with PAYMENT-REQUIRED (v2) + X-PAYMENT-REQUIRED (v1) headers
• GET /lookup?query=<company or domain> — 402 with payment terms ($0.01 USDC); no match → 404
• POST /fulfill — {"tx_hash":"0x...","pack":"25","deliver_to":"..."}
• POST /fulfill-lookup — {"tx_hash":"0x...","query":"<company>"}
• GET /skill.md — agent skill file for the lead lookup (markdown)
• /mcp — MCP streamable-HTTP endpoint (proxied to the sibling MCP server when MCP_PROXY_PORT is set)

Interface reference (for agent/MCP clients)

GET /packs/{25,50,100} → 402 Payment Required

• Headers: PAYMENT-REQUIRED = base64(JSON x402 v2 terms), X-PAYMENT-REQUIRED = base64(JSON x402 v1 terms)
• Body: {error:"payment_required", pack, leads, price_usd, currency:"USDC", network:"eip155:8453", fulfillment, sales_enabled, x402:{x402Version:2, accepts:[{scheme:"exact", network, amount (atomic USDC, 6 decimals), description, mimeType, payTo, maxTimeoutSeconds, asset, extra}], resource:{url, description, mimeType}}, how_to_pay:[...]}
• sales_enabled:false while the seller address is unconfigured (current state); flips automatically once set.

POST /fulfill — body {tx_hash:"0x…", pack:"25"|"50"|"100", deliver_to:"…" (optional)}

• Success, pack 25 → 200 {receipt:"ok", pack:"scout-pack-25", tx_hash, verified_at, leads:{…25-lead pack JSON…}}
• Success, pack 50/100 → 200 {receipt:"ok", pack, tx_hash, verified_at, order_id, status:"queued_for_assembly", eta:"within 24 hours of payment confirmation", deliver_to, note}
• Failure → 402 {error:"payment_not_verified", detail:"sales_paused: receiving address not configured" | "bad_tx_hash" | "already_redeemed" | "tx_not_found" | "tx_not_successful" | "tx_too_old" | "no_matching_usdc_transfer" | "chain_lookup_failed", pay:[…steps…]} or 400 {error:"unknown_pack"|"bad_json"}

Verification rules: tx must be a successful Base USDC transfer of ≥ the pack amount to the configured receiving address, mined <30 days ago, and each tx hash is single-use.

Buying flow

1. GET /packs/25 → read the 402 terms (payTo, exact USDC amount).
2. Standard x402: sign an EIP-3009 authorization for exactly $0.01 USDC on Base to payTo and retry the same request with the signature in the X-PAYMENT (v1) or PAYMENT-SIGNATURE (v2) header. The payment is verified + settled via facilitator and pack 25 is returned immediately (50/100 return a 24h order receipt).
3. Fallback: send exactly $0.01 USDC on Base to payTo yourself, then POST /fulfill with the tx hash.

Payment is verified on-chain (Blockscout free API): the tx must be a successful USDC transfer of ≥ the pack amount to the receiving address. Tx hashes are single-use (replay-protected); txs older than 30 days are rejected.

Config

• SCOUTPACKS_RECEIVING_ADDRESS — the Base address that receives USDC. While unset (or the zero address) the endpoint runs in preview-only mode: sales_enabled=false in 402 bodies and /.well-known/x402, and /fulfill refuses all requests.
• SCOUTPACKS_PUBLIC_BASE — public URL used in 402 resource fields.
• PORT — default 8000.
• MCP_PROXY_PORT — optional (e.g. 8001); when set, /mcp reverse-proxies to the sibling MCP streamable-HTTP server (mcp/http_server.py) on that port — one deploy exposes both the x402 API and a durable-HTTPS MCP endpoint.

Deploy

./run.sh &                                   # localhost:8000

Production (since 2026-10-02) runs on Railway — https://scout-packs-production.up.railway.app is the sole production endpoint. The old localtunnel path (lt-proxy.js, loca.lt subdomains) is dead legacy, retired 2026-10-02 after chronic 503s. On normal infra for a fresh deploy, cloudflared tunnel --url http://127.0.0.1:8000 works as usual.

Then register on the open indexes, e.g. 402 Index: POST https://402index.io/api/v1/register with {url, name, protocol:"x402", description, price_usd, payment_asset:"USDC", payment_network:"eip155:8453", category:"data", tags:[...]}.

MCP server (for agent clients)

AI agents can also discover and buy packs from inside MCP clients (Claude Desktop, Cursor, MCP Inspector, agent frameworks) via the MCP server in mcp/:

• list_packs — free. Pack sizes, prices, live sales status, redacted sample.
• buy_pack — returns the exact x402 payment terms and the step-by-step flow; the buying agent's own wallet pays the endpoint. Never moves funds, never holds keys.

Quick start (Python 3.10+, installs the mcp SDK only):

cd mcp && python3 -m venv .venv && .venv/bin/pip install mcp
BASE_URL=https://<endpoint-url> .venv/bin/python scout_packs_mcp.py

Or once published to PyPI: uvx scout-packs-mcp with BASE_URL set. Full docs: mcp/README.md. Registry listings: mcp/REGISTRIES.md.