About l402-search-mcp
l402-search-mcp is an MCP server that gives AI agents access to L402-paywalled web search, charging Lightning sats per query. It holds no wallet keys: the agent pays invoices through its own wallet and returns the payment preimage to retrieve results.
Key features
- 01Request search results through L402
- 02Return an invoice and payment hash
- 03Accept a payment preimage to fetch results
- 04Check endpoint status and pending challenges
- 05Append events to an audit log
Use cases
- 01Buy a single web search with Lightning sats
- 02Let an agent pay using its own wallet limits
- 03Connect to an endpoint using the same L402 dialect
MCP support
Exposes `search` and `search_service_info` tools to MCP clients. Search first returns an invoice; after the agent pays it using its own wallet and supplies the preimage, the server retrieves results from the L402 endpoint.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
npx -y l402-search-mcpSEARCH_SERVICE_URLL402 search endpoint to consume (default: https://llmops-search.fly.dev)Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
2Saved tool list · updated 2w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | The search query. Must be identical on the paid retry. |
| payment_preimage | string | No | 64-hex preimage returned by your wallet after paying the invoice. Omit on the first call. |
Details
From the project READMEl402-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:
search(query)→ returns a bolt11 Lightning invoice +payment_hash- The agent pays the invoice with its own wallet — e.g.
nwc-mcp'snwc_pay_invoice, under the agent's own budget caps 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 · ⚡ [email protected]
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.