402 MCP

402-mcp

Nostr: npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2

L402 client MCP that gives AI agents economic agency. Discover, pay for, and consume Lightning and ecash payment-gated APIs within limits you set: no human registration, no API keys, no middlemen.

• Discover paid APIs on Nostr, no URLs needed upfront
• Auto-pay with Lightning (NWC), Cashu ecash, LNURLcash bearer notes, or human QR fallback
• Credentials cached and encrypted at rest (AES-256-GCM)
• Works with any L402 server: toll-booth, Aperture, or any future implementation

Quick start

There is no install step: npx fetches 402-mcp when your MCP client first starts it. Running npx 402-mcp by hand only starts a stdio server that waits for a client on standard input (stop it with Ctrl+C), so do that to check it launches, not to use it.

1. Connect it to your MCP client

Claude Code:

claude mcp add 402-mcp -- npx 402-mcp

Claude Desktop or Cursor, in the MCP configuration file:

{

"mcpServers": { "402-mcp": { "command": "npx", "args": ["402-mcp"] } } }

2. Try it

Ask Claude: *"Search for paid joke APIs using l402-search"*, no wallet needed, just discovery.

3. Pay for calls (optional): connect an NWC wallet

402-mcp reads the Nostr Wallet Connect URI from a private file, never from an environment variable or a command line. Create the file with owner-only permissions first, then paste the URI into it with an editor so it stays out of your shell history:

mkdir -p ~/.402-mcp

touch ~/.402-mcp/wallet.nwc chmod 600 ~/.402-mcp/wallet.nwc

open ~/.402-mcp/wallet.nwc in an editor, paste the URI on one line, save

The URI comes from your wallet service and looks like this, with your own values in place of the placeholders:

nostr+walletconnect://<wallet-pubkey-hex>?relay=<wss-relay-url>&secret=<secret-hex>

It needs a 64-character hex wallet pubkey, one to eight relay values, one 64-character hex secret, and may carry lud16; any other parameter is rejected. The file must be a regular, non-empty file under 8 KiB, and on macOS and Linux it is refused unless group and other have no permissions (chmod 600). Create the connection with pay_invoice permission and a spending budget (lookup_invoice as well lets l402-reconcile ask the wallet about unknown outcomes). The wallet must support NIP-44 v2 encryption.

Then register 402-mcp with the absolute path ($HOME expands in your shell when you run the command):

claude mcp remove 402-mcp

claude mcp add 402-mcp -e NWC_URI_FILE="$HOME/.402-mcp/wallet.nwc" -e MAX_AUTO_PAY_SATS=1000 -- npx 402-mcp

For Claude Desktop or Cursor, add an env block to the same server entry. JSON does not expand ~ or $HOME, so write out the absolute path of the file you created:

{

"mcpServers": { "402-mcp": { "command": "npx", "args": ["402-mcp"], "env": { "NWC_URI_FILE": "/absolute/path/to/.402-mcp/wallet.nwc", "MAX_AUTO_PAY_SATS": "1000" } } } }

A raw NWC_URI variable is refused at startup. For Cashu, LNURLcash or no wallet at all, and a first paid call, see the full quickstart guide.

Requires Node.js 22.4 or newer.

How it works

graph LR

A["1. l402-config()"] --> B["2. l402-discover(url)"] B --> C["3. Agent reasons about pricing"] C --> D["4. l402-buy-credits() or l402-fetch(autoPay)"] E["5. l402-fetch(url) with stored credential"] D --> E E --> F["6. Data returned

• balance cached"]

Example session:

Agent: "I need routing data from routing.example.com"

1. l402-config() -> nwcConfigured: true, maxAutoPaySats: 1000

1. l402-discover("https://routing.example.com/api/route") -> 10 sats/request, toll-booth detected, tiers available

1. Agent reasons: "I need ~20 requests. The 500-sat tier gives 555 credits. Better value."

1. l402-buy-credits(url, amountSats=500) -> Paid 500 sats, received 555 credits

1. l402-fetch("https://routing.example.com/api/route?from=...&to=...") -> 200 OK, route data, 545 credits remaining

Step 5 needs no autoPay: step 4 stored a credential for that server and l402-fetch sends it. Without a stored credential, l402-fetch pays nothing unless autoPay: true is set; it returns the price and a paymentHash instead (see Spending limits).

For detailed architecture and payment flow diagrams, see docs/architecture.md.

Configuration

NWC_URI and HTTP_AUTH_TOKEN are refused at startup: both secrets are read only from their *_FILE variables. The spend caps, MAX_AUTO_PAY_SATS and FETCH_MAX_RETRIES must be non-negative whole numbers; the timeouts, the size limit and the poll interval at least 1; PORT 1 to 65535.

Transport selection and fallback

When a kind 31402 event advertises multiple URLs (one per transport), 402-mcp selects the best one based on your configuration:

1. Preference first: URLs are tried in TRANSPORT_PREFERENCE order, onion,hns,https,http by default. Use onion, hns, https and http as the values; there is no value for anything else. A URL counts as hns when its TLD is .hns. One whose TLD is merely unfamiliar (.pub, .fyi) is more likely an ICANN name, so it has no value of its own: it counts as a guessed hns name and is tried just after whichever of hns and https comes later in your order, which is just after https by default. If you leave hns out of TRANSPORT_PREFERENCE, such URLs go last.
2. Capability filter: .onion URLs are skipped unless TOR_PROXY or SOCKS_PROXY is set, so without a proxy the default order starts at HNS and clearnet.
3. Availability fallback: if a transport is unreachable (connection refused, timeout), the next URL is tried.

Services can announce multiple endpoints for the same service (same pricing, same macaroon key) on different transports. This is purely for censorship resistance; you do not need to re-authenticate when switching transports. .onion endpoints need TOR_PROXY or SOCKS_PROXY. Handshake endpoints need no configuration, because HNS_GATEWAY_URL has a default, except under SOCKS_PROXY, which switches Handshake lookups off (see Tor and SOCKS5).

Credentials across transports. When l402-fetch is given a service's pubkey (from l402-search), it stores and looks up the credential under that pubkey, so one purchase serves every transport URL passed in urls. Without a pubkey the credential is keyed by the request's origin. Either way the credential records the origins it was bought through and is sent only to those, whatever pubkey a later request names. A macaroon bought through a Tor hidden service therefore works on the clearnet URL when both were in urls at purchase, and is never sent to any other host.

Tor and SOCKS5

• `TOR_PROXY` sends .onion requests through the proxy. Everything else connects directly.
• `SOCKS_PROXY` sends every request to a paid API through the proxy, including redirects. Host names are resolved by the proxy, never by this machine, so a Tor proxy hides both your IP and the names you look up. The SSRF guard still refuses private IP literals and local names such as localhost; it cannot see what a name resolves to on the far side, which Tor exits refuse for private ranges anyway.

Neither setting covers wallet or discovery traffic: NWC relays, Cashu and LNURLcash mints, and the Nostr relays l402-search queries still connect directly. Handshake lookups are switched off under SOCKS_PROXY, because the DNS-over-HTTPS query would go around the proxy.

SOCKS5 support comes from undici's Socks5ProxyAgent, which Node marks experimental; expect one ExperimentalWarning on stderr when a proxy is configured.

Tools

Core L402 (any server)

| l402-fetch-preview | Show what an endpoint costs withou