Paywall MCP server

paywall-mcp

Paywall ANY stdio MCP server with Lightning, without modifying it. paywall-mcp is a generic sidecar: configure it with an upstream MCP server command and a per-tool price map, and it transparently:

• Forwards tools/list from the upstream to the LLM client, with prices appended to each tool's description.
• Intercepts tools/call: free tools pass through; priced tools require a paid Lightning invoice (via Nostr Wallet Connect / NIP-47) before the call is forwarded.

No code changes to the upstream server. Works with Anthropic's reference MCP servers, your own, or any third-party MCP server that speaks stdio.

v0.1 — proxy + payment gate complete. Spawns a stdio upstream as a child process; per-tool pricing via env; in-memory invoice cache + replay protection; audit log; read-only mode. Persistent cache + HTTP/SSE upstream transport deferred to v0.2.

Why this exists

Modern paid-API patterns (Lightning paywall, L402, micropayments) exist for HTTP but the MCP ecosystem has no standard for paid tool calls. Building it into each individual server is repetitive and error-prone. paywall-mcp is the missing sidecar: write your tools as a normal MCP server, then wrap it with paywall-mcp to charge sats per call.

How the dual-call pattern works

For any priced tool:

1. First call — LLM calls pricedtool({...args}) without paymenthash. paywall-mcp issues a bolt11 invoice through your NWC wallet and returns:

{
     "error": "payment_required",
     "invoice": "lnbc...",
     "payment_hash": "abc123...",
     "amount_sats": 21,
     "expires_in_seconds": 600,
     "next_step": "Pay this bolt11 ..."
   }

1. Payment — the LLM (or its operator) pays the invoice. Easiest path: use nwc-mcp — the same LLM can call nwcpayinvoice to settle.
2. Second call — LLM calls pricedtool({...args, paymenthash: "abc123..."}). paywall-mcp verifies settlement via NWC lookupinvoice, strips paymenthash from the args, forwards the original call to the upstream, returns the upstream's result.

Replay protection: the same payment_hash cannot be redeemed twice. Buyers pay a fresh invoice for each call.

What you can build with it

• Charge sats for premium tools in an MCP server you already have, by adding one wrapper process.
• Per-tool pricing tiers — freelookup: 0, premiumanalysis: 100, rarealphasignal: 5000. Buyers see prices in tool descriptions.
• Bundle-and-resell third-party MCP servers — wrap someone else's open-source MCP server with your paywall and offer it as a managed paid service.
• A/B test pricing — adjust PAYWALLPRICEMAP in env, restart, you're at the new price.
• Time-limited promotional pricing — start at 21 sats, raise to 100 sats once usage proves the value.

Requirements

• Node 20+
• An existing stdio MCP server to wrap (paywall-mcp doesn't host tools itself; it gates an upstream's tools).
• A NIP-47 NWC connection string for the seller's receive wallet. makeinvoice + lookupinvoice are the only permissions paywall-mcp needs. A receive-only NWC connection is perfectly fine and recommended — paywall-mcp never spends.

Install

# From npm
npx -y paywall-mcp

# From source
git clone <repo>
cd paywall-mcp
corepack enable pnpm
pnpm install
pnpm build

Configure

cp .env.example .env
# edit .env: set PAYWALL_UPSTREAM_COMMAND/ARGS, NWC_CONNECTION_STRING, prices

The server auto-loads .env from its own directory (next to dist/) — deliberately NOT from cwd, to avoid env collisions when running multiple MCP servers in the same Claude Code session.

Required

Shortened. The full README is on GitHub.