io.github.llmops-pro/l402-search-mcp

l402-search-mcp

No-KYC web search for AI agents — paid per query in Lightning sats, via MCP.

This is an MCP client-side server for L402-paywalled search endpoints. It gives any MCP-capable agent (Claude Desktop, Claude Code, Cursor, nostr-merchant, …) a search tool that costs sats instead of an API key:

1. search(query) → returns a bolt11 Lightning invoice + payment_hash
2. The agent pays the invoice with its own wallet — e.g. nwc-mcp's nwc_pay_invoice, under the agent's own budget caps
3. search(query, payment_preimage) → JSON results

No account. No API key. No KYC. Each payment buys exactly one search.

By default it points at https://llmops-search.fly.dev (50 sats/search, run by us), but SEARCH_SERVICE_URL works with any endpoint speaking the same L402 dialect.

The trust model (read this)

This server holds NO keys. Not a wallet connection, not an nsec, nothing. Payment happens in the agent's wallet, where the agent's own budget caps, allowlists, and audit logs apply. l402-search-mcp only:

• relays the L402 challenge (invoice) to the agent,
• remembers which macaroon belongs to which payment_hash (so the agent only handles the preimage its wallet already returned),
• makes the authorized retry.

Worst-case compromise of this process leaks pending search queries — never money.

Install

npx -y l402-search-mcp

Claude Code (project scope):

claude mcp add l402-search -s project -- npx -y l402-search-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "l402-search": { "command": "npx", "args": ["-y", "l402-search-mcp"] }
  }
}

Pair it with a wallet server (e.g. nwc-mcp) so the agent can actually pay.

Tools

Tool	Price	What it does
search	sats (set by the endpoint; 50 on the default)	First call returns the invoice; the call with payment_preimage returns results.
search_service_info	free	Endpoint reachability, pending challenges, flow explainer.

Configuration

Everything is optional — the defaults work. Set in the environment or a .env next to the install (never read from cwd):

SEARCH_SERVICE_URL=https://llmops-search.fly.dev  # any L402 search endpoint
CHALLENGE_TTL_SECONDS=900                          # match the endpoint's macaroon TTL
AUDIT_LOG_PATH=./l402-search-mcp-audit.log         # NDJSON, append-only
HTTP_TIMEOUT_MS=15000

The flow, end to end

agent                    l402-search-mcp              endpoint              agent's wallet
  │  search("foo")            │                          │                       │
  │ ────────────────────────► │  GET /search?q=foo       │                       │
  │                           │ ───────────────────────► │                       │
  │                           │  402 {macaroon, invoice} │                       │
  │  {invoice, payment_hash}  │ ◄─────────────────────── │                       │
  │ ◄──────────────────────── │  (macaroon cached)       │                       │
  │  nwc_pay_invoice(invoice) │                          │                       │
  │ ──────────────────────────┼──────────────────────────┼─────────────────────► │
  │  {preimage}               │                          │                       │
  │ ◄─────────────────────────┼──────────────────────────┼────────────────────── │
  │  search("foo", preimage)  │                          │                       │
  │ ────────────────────────► │  GET + Authorization:    │                       │
  │                           │  L402 macaroon:preimage  │                       │
  │                           │ ───────────────────────► │                       │
  │  {results}                │  200 {results}           │                       │
  │ ◄──────────────────────── │ ◄─────────────────────── │                       │

The macaroon never round-trips through the LLM — the agent only sees the invoice and hands back the preimage its wallet returned. sha256(preimage) = payment_hash recovers the rest.

Audit log

NDJSON, one line per event: startup, challenge_received, results_received, unknown_preimage, endpoint_error. Same shape as the other servers in the kit.

Part of the LLMOps.Pro agent-payments kit

nwc-mcp (wallet) · nostr-ops-mcp (NOSTR identity/publishing) · marketplace-mcp (storefront) · albyhub-admin-mcp (node admin) · paywall-mcp (sell YOUR tools for sats) · l402-search-mcp (buy search with sats)

MIT. Built by LLMOps.Pro · ⚡ sovereigncitizens@getalby.com