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

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