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`](https://npmjs.com/package/nwc-mcp) — the same LLM can call `nwc_pay_invoice` to settle.

1. 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 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

Required when any tool has a non-zero price

Pricing

Optional

---

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 ...

1. premium_compliment({}) → returns invoice + payment_hash
2. nwc_pay_invoice(invoice) → buyer pays
3. 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.