mcp-l402-gate-example

Minimal MCP server showing @powforge/mcp-l402-gate in action.

One tool, bitcoin_data, fetches current BTC/USD price plus recommended mempool fees from mempool.space. Each call is gated by:

1. An L402 Lightning invoice (the caller pays sats per call).

2. A Depth-of-Identity score lookup against the public PowForge oracle. Below the threshold, paying does not get you through.

L402 alone proves a caller paid. L402 + DoI proves they paid and carry a per-pubkey reputation that survives across sessions and costs irreversible work to fake. That second half is the part most MCP billing kits skip.

Quickstart

git clone https://github.com/zekebuilds-lab/mcp-l402-gate-example
cd mcp-l402-gate-example
cp .env.example .env       # fill in GATE_HMAC_SECRET and LNBits creds
npm install
npm start

Server logs the tool URL and oracle on boot. Default port is 3100.

Related MCP server: l402-kit-mcp

Test it with curl

First call has no auth, so the gate returns a 402 with an invoice:

curl -i -X POST http://localhost:3100/tools/bitcoin_data \
  -H 'Content-Type: application/json' \
  -H 'X-Caller-Pubkey: 02a1b2c3...your-hex-pubkey' \
  -d '{}'

Expected response:

HTTP/1.1 402 Payment Required
WWW-Authenticate: L402 macaroon="...", invoice="lnbc1..."
Content-Type: application/json

{
  "error": "payment required",
  "macaroon": "...",
  "invoice": "lnbc1...",
  "payment_hash": "..."
}

Pay the invoice field (any LN wallet), capture the preimage, then retry:

curl -i -X POST http://localhost:3100/tools/bitcoin_data \
  -H 'Content-Type: application/json' \
  -H 'X-Caller-Pubkey: 02a1b2c3...your-hex-pubkey' \
  -H 'Authorization: L402 <macaroon>:<preimage>' \
  -d '{}'

You get back the BTC price, mempool fee estimates, and the caller's DoI score.

The manifest is also exposed for MCP clients that introspect tool catalogs:

curl http://localhost:3100/manifest.json

Configuration

DoI score thresholds

These are the same buckets the oracle returns as rank. Pick the one that matches how expensive a wrong call is:

How the gate works

Without the gate, a 402 + macaroon flow proves the caller paid 10 sats. A fresh attacker wallet pays the same 10 sats. That is fine wire format and weak abuse control.

@powforge/mcp-l402-gate keeps the L402 invoice and adds a second check: when the macaroon verifies, the gate calls the DoI oracle for the caller's pubkey, gets back a Schnorr-signed score, and compares to MIN_SCORE. The score is composed from observable irreversible work across four dimensions (social, access, vouch, economic), so a fresh sybil cannot grind it in a minute.

The full failure-mode table is in @powforge/mcp-l402-gate README.

Files

• server.js - the MCP server, ~110 lines.

• .env.example - copy to .env and fill in.

• package.json - depends on express and @powforge/mcp-l402-gate.

Links

• npm: @powforge/mcp-l402-gate

• Docs and pricing: powforge.dev/mcp

• Public DoI oracle: identity.powforge.dev

License

MIT.