io.github.llmops-pro/paywall-mcp

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 priced_tool({...args}) without payment_hash. 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 ..."
   }
   

2. Payment — the LLM (or its operator) pays the invoice. Easiest path: use nwc-mcp — the same LLM can call nwc_pay_invoice to settle.
3. Second call — LLM calls priced_tool({...args, payment_hash: "abc123..."}). paywall-mcp verifies settlement via NWC lookup_invoice, strips payment_hash 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 — free_lookup: 0, premium_analysis: 100, rare_alpha_signal: 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 PAYWALL_PRICE_MAP 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. make_invoice + lookup_invoice 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

Var	Purpose
PAYWALL_UPSTREAM_COMMAND	Executable to spawn as the upstream MCP server (e.g., node).
PAYWALL_UPSTREAM_ARGS	JSON array of args passed to the upstream command (e.g., ["/path/to/upstream/dist/index.js"]).

Required when any tool has a non-zero price

Var	Purpose
NWC_CONNECTION_STRING	NIP-47 NWC URI for the seller's RECEIVE wallet. make_invoice + lookup_invoice permissions sufficient. paywall-mcp never spends.

Pricing

Var	Default	Purpose
PAYWALL_DEFAULT_PRICE_SATS	0	Default price for any tool not in the price map. 0 = free passthrough.
PAYWALL_PRICE_MAP	{}	JSON object mapping tool names to sat prices. Per-tool 0 = free; missing = use default. Example: {"premium_compliment":21,"rare_alpha_signal":5000}.

Optional

Var	Default	Purpose
PAYWALL_UPSTREAM_CWD	(parent cwd)	Working directory for the upstream child process.
PAYWALL_UPSTREAM_ENV	(inherits)	JSON object of env-var overrides for the upstream.
PAYWALL_READ_ONLY	false	Disables all paid tool calls (tools/list still works). Useful for maintenance.
PAYWALL_INVOICE_TTL_SECONDS	600	Invoice TTL. Past this, payment_hash is forgotten from cache and the buyer must re-issue.
PAYWALL_PRICE_LABEL_TEMPLATE	"(💰 {price} sats)"	Label appended to each priced tool's description in tools/list. {price} is substituted with the sat amount.
PAYWALL_LOG_PATH	./paywall-mcp.log	Server log.
PAYWALL_AUDIT_PATH	./paywall-mcp-audit.log	NDJSON audit log (one line per call).

---

End-to-end example: paywall the bundled paywall-mcp-test server

The companion paywall-mcp-test package exposes a single tool — premium_compliment. It already implements its own paywall pattern internally, but it's also a convenient stand-in for "any upstream MCP server" to demonstrate paywall-mcp itself.

.env:

PAYWALL_UPSTREAM_COMMAND=node
PAYWALL_UPSTREAM_ARGS=["/abs/path/to/paywall-mcp-test/dist/index.js"]

NWC_CONNECTION_STRING=nostr+walletconnect://...

PAYWALL_DEFAULT_PRICE_SATS=21
PAYWALL_PRICE_MAP={"premium_compliment":21}

Wire paywall-mcp (not the upstream directly) into your MCP client:

{
  "mcpServers": {
    "paywall": {
      "command": "npx",
      "args": ["-y", "paywall-mcp"],
      "env": {}
    }
  }
}

Now from your agent:

1. tools/list  → premium_compliment ... (💰 21 sats) This tool requires ...
2. premium_compliment({})  → returns invoice + payment_hash
3. nwc_pay_invoice(invoice)  → buyer pays
4. premium_compliment({ payment_hash: "..." })  → upstream's result returned

---

Safety model

tools/list      → upstream.listTools() → augment descriptions with prices → return
tools/call:
  if price == 0           → upstream.callTool(args)                  (passthrough)
  elif PAYWALL_READ_ONLY  → refuse with paywall_read_only            (block)
  elif no payment_hash    → gate.issue() → return bolt11 + hash      (issue)
  elif bad hash format    → refuse with invalid_payment_hash         (block)
  else (have hash):
      gate.verify() ──┬─ unknown_payment_hash         → block
                      ├─ payment_hash_already_redeemed → block (replay)
                      ├─ payment_hash_tool_mismatch    → block
                      ├─ payment_not_settled           → block
                      └─ ok → strip hash → upstream.callTool()      (paid passthrough)

Audit log entries (NDJSON, one per request):

• outcome: "ok" — invoice issued, free passthrough, or paid passthrough completed
• outcome: "blocked" — read-only refusal, invalid hash, replay, mismatch, not-settled
• outcome: "error" — upstream call failed, NWC lookup_invoice failed, etc.

Tail the audit log for ground truth — independent of whatever the LLM tells you.

tail -f paywall-mcp-audit.log | jq .

---

Wire into Claude Desktop / Claude Code / Cursor

{
  "mcpServers": {
    "paywall": {
      "command": "npx",
      "args": ["-y", "paywall-mcp"],
      "env": {}
    }
  }
}

Same .env-via-binary-dir pattern as the rest of the substrate — leave env empty in the client config; secrets stay in paywall-mcp/.env.

---

Testing

pnpm typecheck
pnpm test        # 13 vitest cases (config resolution + payment-gate state machine)
pnpm build       # ~18 KB ESM bundle

---

Companion servers

• nwc-mcp — Lightning wallet for the buyer. Lets the agent pay the invoices paywall-mcp issues. The matching half of the agent-pays-a-paid-tool loop.
• nostr-ops-mcp — NOSTR identity, publishing, encrypted DMs.
• marketplace-mcp — Run a NIP-15 / Shopstr storefront from an agent.
• albyhub-admin-mcp — Alby Hub node-admin via HTTP API.

---

License

MIT — see LICENSE.

Contact / Issues

Built by LLMOps.Pro.

• NOSTR: npub1hdg932jvwc3jdvkqywgqv0ue4nn60exrf92asy8mtazt3hjg7d2s2yw0nw — follow, DM, zap.
• Lightning Address: sovereigncitizens@getalby.com — for support zaps and "this was useful" tips.
• Bug reports / feature requests: open a GitHub issue (link forthcoming).
• Security issues: please disclose privately via NOSTR DM before opening a public issue.