mcp-l402-gate-example

Servidor MCP minimalista que muestra @powforge/mcp-l402-gate en acción.

Una herramienta, bitcoin_data, obtiene el precio actual de BTC/USD además de las comisiones recomendadas de mempool desde mempool.space. Cada llamada está protegida por:

1. Una factura Lightning L402 (el llamante paga sats por llamada).

2. Una búsqueda de puntuación Depth-of-Identity (DoI) contra el oráculo público de PowForge. Por debajo del umbral, pagar no te permite pasar.

L402 por sí solo demuestra que un llamante pagó. L402 + DoI demuestra que pagaron y que poseen una reputación por clave pública que sobrevive a través de sesiones y cuyo falseamiento requiere un trabajo irreversible. Esa segunda parte es la que la mayoría de los kits de facturación MCP omiten.

Inicio rápido

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

El servidor registra la URL de la herramienta y el oráculo al arrancar. El puerto predeterminado es 3100.

Related MCP server: l402-kit-mcp

Pruébalo con curl

La primera llamada no tiene autenticación, por lo que la puerta devuelve un 402 con una factura:

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

Respuesta esperada:

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

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

Paga el campo invoice (cualquier billetera LN), captura la preimagen y luego vuelve a intentarlo:

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 '{}'

Obtendrás el precio de BTC, las estimaciones de comisiones de mempool y la puntuación DoI del llamante.

El manifiesto también se expone para clientes MCP que inspeccionan catálogos de herramientas:

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

Configuración

Umbrales de puntuación DoI

Estos son los mismos grupos que el oráculo devuelve como rank. Elige el que coincida con lo costosa que es una llamada incorrecta:

Cómo funciona la puerta

Sin la puerta, un flujo de 402 + macaroon demuestra que el llamante pagó 10 sats. Una billetera de atacante nueva paga los mismos 10 sats. Eso es un formato de cable correcto pero un control de abuso débil.

@powforge/mcp-l402-gate mantiene la factura L402 y añade una segunda verificación: cuando el macaroon se verifica, la puerta llama al oráculo DoI para la clave pública del llamante, obtiene una puntuación firmada con Schnorr y la compara con MIN_SCORE. La puntuación se compone de trabajo irreversible observable en cuatro dimensiones (social, acceso, aval, económico), por lo que un sybil nuevo no puede generarla en un minuto.

La tabla completa de modos de fallo está en el README de @powforge/mcp-l402-gate.

Archivos

• server.js - el servidor MCP, ~110 líneas.

• .env.example - copiar a .env y rellenar.

• package.json - depende de express y @powforge/mcp-l402-gate.

Enlaces

• npm: @powforge/mcp-l402-gate

• Documentación y precios: powforge.dev/mcp

• Oráculo DoI público: identity.powforge.dev

Licencia

MIT.