LiveAuth MCP Server

Autenticación de Prueba de Trabajo + Lightning Network para agentes de IA. Envuelve herramientas MCP de pago con recibos firmados L402.

GitHub
1
Prueba este MCPPatrocinado

Documentación

LiveAuth MCP Server

MCP financiado por el llamante (1.3.0): usa el createMcpGate({ publicKey, toolName, fundingMode: 'caller' }) existente. LiveAuthCore verifica el pago del llamante y gestiona la contabilidad; este paquete gestiona los desafíos de pago, el enlace de reintentos y la prevención de ejecución duplicada. Financiación del llamante, ejemplos de API y migración. PoW autentica; no financia herramientas de pago.

npm version MIT license L402 MCP

Autenticación, medición de pago por llamada y recibos firmados para agentes de IA y herramientas MCP: nativo de Bitcoin, respaldado por Lightning y compatible con L402.

Este servidor MCP permite que cualquier agente de IA se autentique contra tu API usando prueba de trabajo (gratis, sin cuenta) o micropagos de la red Lightning (sats), y luego mida y monetice llamadas posteriores a herramientas con precios por llamada, eventos de ingresos idempotentes y recibos firmados con HMAC que los auditores pueden verificar sin conexión.

Úsalo cuando quieras:

  • Proteger una API o herramienta MCP detrás de un costo real de cómputo o sats reales (anti-spam por diseño, no por CAPTCHA).
  • Cobrar a agentes de IA por llamada sin registrarlos con una cuenta.
  • Emitir un rastro de auditoría a prueba de manipulaciones (mcp-call-receipt-v1 firmado) por cada invocación de herramienta de pago.
  • Ofrecer acceso a paquetes L402 respaldados por Lightning para sesiones MCP prepagadas.

Pruébalo en 5 segundos — sin cuenta, sin clave de API:

npx @liveauth-labs/mcp-server

Sin configuración, el servidor usa el proyecto demo anónimo de LiveAuth y el flujo PoW real. Añade LIVEAUTH_API_KEY solo cuando necesites la política, los precios o la atribución de un proyecto específico.

Herramientas Disponibles (Glama / auto-descubrimiento MCP)

HerramientaPropósito
liveauth_mcp_startIniciar una sesión. Devuelve un desafío PoW, una factura Lightning o una pista de paquete L402.
liveauth_mcp_confirmEnviar un desafío PoW resuelto, una factura Lightning pagada o un macarrón L402 → recibe un JWT.
liveauth_mcp_chargeMedir el uso después de una llamada. Con toolName, resuelve el precio de la herramienta registrada y registra un evento de ingresos pagado.
liveauth_mcp_refreshIntercambiar un token de refresco por un nuevo JWT — sin necesidad de reautenticación.
liveauth_mcp_statusConsultar el estado de la sesión/pago (confirmación Lightning, expiración).
liveauth_mcp_lnurlObtener la factura BOLT11 para una sesión (compatible con lnget).
liveauth_mcp_payment_confirmConfirmar un pago del llamante con la sesión actual; luego reintentar la operación original.
liveauth_mcp_usageConsultar el presupuesto restante, las llamadas usadas y las ventanas de límite de tasa.

Los esquemas completos de parámetros y respuestas están en la Referencia de Herramientas a continuación.

Inicio Rápido en 5 Minutos

Opción 1 — PoW sin credenciales (sin cuenta, sin clave, sin billetera)

npx @liveauth-labs/mcp-server

En un cliente MCP, llama a liveauth_mcp_start, luego llama a liveauth_mcp_confirm solo con el quoteId devuelto. El paquete reutiliza su solucionador PoW existente localmente y la API de LiveAuth verifica el desafío firmado antes de emitir un JWT de sesión de corta duración.

Opción 2 — Modo Producción

  1. Obtén una clave de API en liveauth.app.
  2. Añade a claude_desktop_config.json de Claude Desktop:
{
  "mcpServers": {
    "liveauth": {
      "command": "npx",
      "args": ["-y", "@liveauth-labs/mcp-server"],
      "env": {
        "LIVEAUTH_API_BASE": "https://api.liveauth.app",
        "LIVEAUTH_API_KEY": "la_pk_your_public_key"
      }
    }
  }
}
  1. Reinicia Claude. Listo.

Opción 3 — Programático (CLI / SDK)

export LIVEAUTH_API_KEY=la_pk_xxx
npx @liveauth-labs/mcp-server

El paquete también es un SDK de TypeScript — consulta Uso del SDK a continuación. El binario CLI es liveauth-mcp.

¿Por qué LiveAuth?

Para proveedores de API / desarrolladores de herramientas:

  • Detén bots en la capa de protocolo. PoW y los sats de Lightning no son reproducibles, no son suplantables y no requieren cuentas de usuario.
  • Cobra por llamada en sats. Firmamos un recibo que puedes mostrar a auditores, clientes o tu contador.
  • Envuelve cualquier herramienta MCP con una línea (createMcpGate) y obtienes ingresos por herramienta, precios mín/máx por herramienta y reintentos idempotentes.

Para agentes de IA / constructores de agentes:

  • Acceso sin permisos a APIs de pago — resuelve un PoW o paga sats, obtén un JWT. Sin registro, sin correo, sin baile de OAuth.
  • Usa PoW, facturas Lightning o macarrones de paquete L402 para acceso de agentes.
  • Los proyectos pueden liquidar a través de un nodo Lightning personalizado cuando está configurado; de lo contrario, los pagos usan el nodo configurado por LiveAuthCore.

Las matemáticas que importan: si tu herramienta está siendo extraída por un bot, cobrar 1 sat por llamada es suficiente para hacer que el extractor no sea rentable. Llamamos a esto economía de costo de ataque, y es la razón principal de nuestra existencia.

Instalación

npm install -g @liveauth-labs/mcp-server

O úsalo directamente con npx:

npx @liveauth-labs/mcp-server

Goose

LiveAuth para Goose usa el mismo servidor MCP stdio basado en estándares que cualquier otro cliente—no hay envoltorio de Goose, demonio ni runtime de autenticación duplicado.

Instalar en Goose

O imprime el enlace profundo oficial y los respaldos actuales:

npx @liveauth-labs/mcp-server setup goose

Para una sesión CLI de Goose única:

goose session --with-extension "liveauth:npx -y @liveauth-labs/mcp-server"

Configuración manual de stdio de Goose, cuando el enlace profundo no esté disponible:

extensions:
  liveauth:
    type: stdio
    name: LiveAuth
    enabled: true
    cmd: npx
    args: ["-y", "@liveauth-labs/mcp-server"]
    env_keys: []
    envs: {}
    timeout: 300

No edites una configuración existente de Goose de forma destructiva. Prefiere el enlace profundo o goose configure; si añades configuración de proyecto más tarde, introdúcela a través de la configuración de secretos de la extensión de Goose en lugar de YAML de texto plano compartido.

Prueba rápida de Goose

Pregunta a Goose:

Usa LiveAuth para iniciar el flujo de autenticación predeterminado. Confirma la cotización devuelta, luego muestra mi uso de LiveAuth.

El flujo inicial usa el desafío PoW del proyecto demo anónimo y no requiere una billetera. Una clave pública de proyecto es opcional:

VariableCuándo configurarla
LIVEAUTH_API_KEYPolítica, precios y atribución específicos del proyecto.
LIVEAUTH_API_BASEUna API de LiveAuth autoalojada en lugar de https://api.liveauth.app.
LIVEAUTH_DEMO=trueOptar explícitamente por la demo Lightning simulada localmente más antigua.

Cuando se solicita un flujo de pago, los resultados de la herramienta conservan los campos de factura existentes y también incluyen datos estructurados portátiles:

{
  "lightning": {
    "invoice": "lnbc...",
    "lightningUri": "lightning:lnbc...",
    "amountSats": 21,
    "expiresAt": "2030-03-17T17:46:40.000Z",
    "status": "pending"
  }
}

Los clientes con soporte de MCP Apps pueden renderizar el QR incluido, la acción de Abrir Billetera, la expiración y el estado en vivo pagado/pendiente/expirado. Otros clientes reciben el JSON y el contenido de la imagen QR como resultados MCP ordinarios.

Solución de problemas de Goose

  • Si el enlace no se abre, ejecuta npx @liveauth-labs/mcp-server setup goose y usa su respaldo de una sesión o manual.
  • Si npx no está disponible, instala una versión actual de Node.js (Node 18 o más reciente).
  • Si una clave de proyecto proporcionada es rechazada, elimínala para verificar el flujo PoW anónimo; las claves inválidas y revocadas intencionalmente no recurren a la demo.
  • Si una factura Lightning expira, llama a liveauth_mcp_start nuevamente para obtener una cotización nueva.
  • Mantén los tokens de refresco y cualquier credencial no pública fuera de los registros y la configuración de texto plano.

LiveAuth permite que los agentes adquieran autorización en tiempo de ejecución en lugar de requerir que cada herramienta esté aprovisionada con credenciales permanentes de antemano.

Uso del SDK

El paquete también se puede importar como SDK de TypeScript/JavaScript. Importar el paquete no inicia el servidor MCP stdio; el CLI vive en el binario liveauth-mcp.

Helper de Autenticación de Cliente

import { createMcpClient } from '@liveauth-labs/mcp-server';

const liveauth = createMcpClient({
  publicKey: 'la_pk_xxx',
  baseUrl: 'https://api.liveauth.app',
  onInvoice(invoice) {
    // Render invoice.bolt11 as a QR code for a paid Lightning test.
    console.log(invoice.bolt11);
  },
});

const session = await liveauth.start();
const token = await liveauth.confirm(session);

console.log(token.jwt);

El cliente almacena JWTs confirmados, los refresca antes de la expiración cuando se devuelve un token de refresco, y expone el token actual a través de liveauth.token. Llama a liveauth.destroy() cuando tu aplicación se esté cerrando para limpiar el estado del token y los temporizadores de refresco.

Para PoW, config.publicKey es la credencial enviada en X-LW-Public. Puede ser la clave pública principal del proyecto o una clave pública de API activa perteneciente a ese proyecto. La API devuelve la clave canónica del proyecto en session.powChallenge.projectPublicKey; el solucionador aplica hash a esa clave devuelta, y la confirmación aún envía la credencial configurada. Estas dos cadenas de clave pueden diferir legítimamente, por lo que compararlas para igualdad no es una verificación de aislamiento de proyecto.

Usa sesiones de tu endpoint de API de LiveAuth de confianza. El servidor vincula la cotización y el desafío firmado al proyecto resuelto y emite un JWT con projectId y authType. Para diagnósticos, compara el projectId del JWT con el ID de proyecto esperado de tu consola, sin registrar el token. Decodificar claims por sí solo no verifica una firma JWT.

Para requerir una factura de pago real:

const session = await liveauth.start({ forceLightning: true });
console.log(session.invoice?.bolt11);

// Poll this after the invoice is paid.
const token = await liveauth.confirmLightning(session);

Helper de Puerta de Servidor

import { createMcpGate } from '@liveauth-labs/mcp-server';

const gate = createMcpGate({
  publicKey: 'la_pk_xxx',
  baseUrl: 'https://api.liveauth.app',
});

const result = await gate.invoke(
  jwtFromYourTransport,
  { message: 'hello' },
  async (input, context) => ({
    content: [{ type: 'text', text: input.message }],
    charge: context.liveAuth.charge,
  }),
  {}
);

gate.invoke(...) valida el JWT, cobra el costo configurado en sats o el predeterminado del proyecto backend, y pasa context.liveAuth a tu manejador. El nombre más antiguo gate.gateTool(...) aún es compatible.

Atribución de Herramientas de Pago

Si tu servidor MCP tiene un ID de herramienta LiveAuth registrado, pasa toolId al crear la puerta. Los cargos entonces van a:

POST /api/mcp/tools/{toolId}/charge

en lugar del endpoint genérico heredado:

POST /api/mcp/charge

También puedes pasar un slug/nombre de herramienta registrado como toolName. En ese modo, los cargos van al endpoint genérico con la identidad de la herramienta en el cuerpo:

POST /api/mcp/charge

Los cargos de herramientas conservan las mismas verificaciones de presupuesto de sesión, pero también registran un evento de ingresos inmutable con sats brutos, tarifa de plataforma de LiveAuth, sats netos del desarrollador, nombre del método de la herramienta, proyecto/sesión/token de pago, metadatos y clave de idempotencia. Cuando costSats se omite, LiveAuthCore usa el precio predeterminado de la herramienta registrada; sin toolId o toolName, recurre al precio global MCP del proyecto.

Las herramientas registradas también pueden tener una URL de webhook de llamada de pago. En cada nueva llamada de pago exitosa, LiveAuthCore pone en cola un webhook liveauth.mcp.tool.paid_call con la identidad de la herramienta, sats brutos/plataforma/netos, ID del evento de ingresos, metadatos y el recibo firmado. Si la URL del webhook de la herramienta está en blanco, LiveAuthCore recurre a la URL del webhook del proyecto; los reintentos idempotentes no ponen en cola duplicados.

import { createMcpGate } from '@liveauth-labs/mcp-server';

const gate = createMcpGate({
  publicKey: process.env.LIVEAUTH_PUBLIC_KEY!,
  baseUrl: process.env.LIVEAUTH_API_URL ?? 'https://api.liveauth.app',
  toolName: 'paid-research-tool',
});

const result = await gate.invoke(
  jwtFromYourTransport,
  { url: 'https://example.com' },
  async (input, context) => {
    const page = await fetch(input.url).then(r => r.text());

    return {
      text: page,
      revenueEventId: context.liveAuth.charge.revenueEventId,
      receipt: context.liveAuth.charge.receipt,
      netSats: context.liveAuth.charge.netSats,
    };
  },
  { requestId: 'req_123' },
  {
    toolMethodName: 'web_fetch',
    idempotencyKey: 'req_123',
    agentId: 'agent_abc',
    metadata: {
      urlHost: new URL('https://example.com').hostname,
    },
  }
);

Cuando toolId o toolName está configurado, GateToolOptions soporta:

OpciónPropósito
costSatsSats opcionales a cobrar por esta llamada. Omite para usar el precio de la herramienta registrada o el precio global del proyecto.
toolNameSlug/nombre de herramienta opcional por llamada al usar el endpoint genérico.
toolMethodNameMétodo dentro de la herramienta, como web_fetch o search.
idempotencyKeyClave segura para reintentos. Reutilizarla para la misma herramienta devuelve el evento de ingresos original y el recibo firmado en lugar de cobrar dos veces.
agentIdIdentificador opcional de llamante/agente para informes.
metadataObjeto JSON pequeño para contexto de auditoría. No almacenes salida privada de la herramienta aquí.

Las respuestas de cargos de herramientas incluyen los contadores de presupuesto normales más la contabilidad de ingresos:

{
  "status": "ok",
  "callsUsed": 3,
  "satsUsed": 15,
  "grossSats": 5,
  "platformFeeSats": 1,
  "netSats": 4,
  "feeBasisPoints": 500,
  "revenueEventId": "event-guid",
  "toolId": "tool-guid",
  "toolName": "Paid Research Tool",
  "toolSlug": "paid-research-tool",
  "receipt": {
    "version": "mcp-call-receipt-v1",
    "payload": "base64url-canonical-json",
    "signature": "base64url-hmac-sha256",
    "signatureAlgorithm": "HMAC-SHA256",
    "keyId": "liveauth-mcp-receipt-v1",
    "body": {
      "receiptId": "mcp_receipt_eventguid",
      "revenueEventId": "event-guid",
      "mcpToolId": "tool-guid",
      "toolName": "Paid Research Tool",
      "toolSlug": "paid-research-tool",
      "toolMethodName": "web_fetch",
      "grossSats": 5,
      "platformFeeSats": 1,
      "netSats": 4,
      "idempotencyKey": "req_123"
    }
  }
}

El recibo es un artefacto de auditoría firmado por llamada devuelto por LiveAuthCore para cargos de herramientas de pago. Guárdalo con el resultado de tu herramienta cuando necesites prueba de cargo o conciliación posterior.

Si no se configura toolId o toolName, el SDK sigue usando /api/mcp/charge para la medición de uso compatible con versiones anteriores.

Configuración

Claude Desktop

Añade a tu claude_desktop_config.json:

{
  "mcpServers": {
    "liveauth": {
      "command": "npx",
      "args": ["-y", "@liveauth-labs/mcp-server"],
      "env": {
        "LIVEAUTH_API_BASE": "https://api.liveauth.app",
        "LIVEAUTH_API_KEY": "la_pk_your_public_key"
      }
    }
  }
}

Modo sin credenciales: Si omites LIVEAUTH_API_KEY, el servidor llama a los endpoints MCP normales sin un encabezado de proyecto. LiveAuth vincula su proyecto demo anónimo configurado, devuelve un desafío PoW firmado y preserva las verificaciones normales de JWT, límite de tasa y medición. LIVEAUTH_DEMO=true sigue siendo una opción explícita para la vista previa Lightning simulada localmente más antigua.

Otras variables de entorno:

VariablePredeterminadoPropósito
LIVEAUTH_API_KEY(sin configurar)Tu clave pública de proyecto LiveAuth (la_pk_…).
LIVEAUTH_API_BASEhttps://api.liveauth.appAnulación para LiveAuth autoalojado.
LIVEAUTH_DEMOfalseUsar explícitamente la demo Lightning simulada localmente heredada.

Otros Clientes MCP

El servidor habla stdio (JSON-RPC 2.0). Inícialo con:

liveauth-mcp

También funciona con cualquier cliente compatible con MCP: Cursor, VS Code, ChatGPT, Windsurf, Continue, Cline.

Referencia de Herramientas

Esquemas completos para cada herramienta MCP. Cada herramienta es compatible con JSON-RPC 2.0 y probada bajo src/index.test.ts y src/cli.test.ts.

liveauth_mcp_start

Inicia una nueva sesión MCP de LiveAuth. Devuelve un desafío PoW por defecto, o una factura Lightning si forceLightning=true. Parámetros:

  • forceLightning (booleano, opcional): Si es true, solicita una factura Lightning en lugar del desafío PoW
  • forceL402 (booleano, opcional): Si es true, inicia una sesión que debe confirmarse con un macarrón de paquete L402

Devuelve (PoW):

{
  "quoteId": "uuid-of-session",
  "powChallenge": {
    "projectId": "guid",
    "projectPublicKey": "la_pk_...",
    "challengeHex": "a1b2c3...",
    "targetHex": "0000ffff...",
    "difficultyBits": 18,
    "expiresAtUnix": 1234567890,
    "signature": "sig..."
  },
  "invoice": null
}

Devuelve (Lightning):

{
  "quoteId": "uuid-of-session",
  "powChallenge": null,
  "invoice": {
    "bolt11": "lnbc...",
    "amountSats": 50,
    "expiresAtUnix": 1234567890,
    "paymentHash": "abc123..."
  },
  "lightning": {
    "invoice": "lnbc...",
    "lightningUri": "lightning:lnbc...",
    "amountSats": 50,
    "expiresAt": "2009-02-13T23:31:30.000Z",
    "expiresAtUnix": 1234567890,
    "status": "pending"
  }
}

Devuelve (paquete L402):

{
  "quoteId": "uuid-of-session",
  "powChallenge": null,
  "invoice": null,
  "authHint": "l402_bundle"
}

liveauth_mcp_confirm

Envía un desafío de prueba de trabajo resuelto, permite que el paquete resuelva su desafío en caché, consulta un pago Lightning o presenta un macarrón L402 para recibir un token de autenticación JWT.

Parámetros:

  • quoteId (cadena): El quoteId de la respuesta de inicio
  • challengeHex (cadena, opcional, solo PoW): El hex del desafío de la respuesta de inicio
  • nonce (número, opcional, solo PoW): El nonce que resuelve el desafío PoW
  • hashHex (cadena, opcional, solo PoW): El hash resultante (sha256 de projectPublicKey:challengeHex:nonce)
  • expiresAtUnix (número, opcional, solo PoW): Marca de tiempo de expiración del desafío
  • difficultyBits (número, opcional, solo PoW): Bits de dificultad del desafío
  • signature (cadena, opcional, solo PoW): Firma del desafío
  • macaroon (cadena, solo L402): Macarrón de paquete devuelto del flujo de reclamo del paquete L402

Cuando el desafío proviene de este servidor MCP, llamar a confirm con quoteId solo reutiliza el solucionador PoW existente del paquete. Los campos de solución explícitos siguen siendo compatibles por compatibilidad.

Devuelve:

{
  "jwt": "eyJhbGc...",
  "expiresIn": 600,
  "remainingBudgetSats": 10000,
  "refreshToken": "abc123def456..."
}

Nota: Guarda el refreshToken de forma segura. Se devuelve en los datos de la herramienta MCP pero nunca se escribe en stderr ni en los registros de la aplicación. Usa liveauth_mcp_refresh para obtener un nuevo JWT sin volver a autenticarte.

liveauth_mcp_charge

Mide el uso de la API después de realizar una llamada autenticada. El servidor MCP incluido llama al endpoint genérico /api/mcp/charge. Proporcionar toolName permite que LiveAuth resuelva una herramienta registrada, aplique su precio configurado y cree un evento de ingresos de herramienta de pago; omitir toolName mantiene la medición genérica compatible con versiones anteriores.

Parámetros:

  • callCostSats (número, opcional): Costo de la llamada a la API en sats. Omítelo para usar el precio del backend.
  • toolName (cadena, opcional): Nombre/identificador de la herramienta MCP registrada para precios y atribución por herramienta.

Devuelve:

{
  "status": "ok",
  "callsUsed": 5,
  "satsUsed": 15
}

Si se excede el presupuesto:

{
  "status": "deny",
  "callsUsed": 100,
  "satsUsed": 1000,
  "reason": "budget_exceeded"
}

liveauth_mcp_status

Verifica el estado de una sesión MCP. Úsalo para consultar la confirmación del pago Lightning.

Parámetros:

  • quoteId (cadena): El quoteId de la respuesta de inicio

Devuelve:

{
  "quoteId": "uuid-of-session",
  "status": "pending",
  "paymentStatus": "pending",
  "expiresAt": "2026-02-17T12:00:00Z"
}

Cuando paymentStatus es "paid", la sesión está confirmada. Llama a liveauth_mcp_confirm nuevamente para obtener el JWT.

liveauth_mcp_lnurl

Obtén la factura Lightning de una sesión (compatible con lnget). Úsalo para recuperar la factura BOLT11 para el pago con cualquier billetera Lightning.

Parámetros:

  • quoteId (cadena): El quoteId de la respuesta de inicio

Devuelve:

{
  "pr": "lnbc2100n1...",
  "routes": []
}

Nota: Esto es compatible con lnget y otras herramientas de pago Lightning. Úsalo para consultar la factura cuando liveauth_mcp_confirm devuelva "payment pending".

liveauth_mcp_usage

Consulta el uso actual y el presupuesto restante sin realizar un cargo. Úsalo para verificar el estado antes de hacer llamadas a la API.

Parámetros: (ninguno requerido)

Devuelve:

{
  "status": "active",
  "callsUsed": 5,
  "satsUsed": 15,
  "maxSatsPerDay": 10000,
  "remainingBudgetSats": 9985,
  "maxCallsPerMinute": 60,
  "expiresAt": "2026-02-17T12:00:00Z",
  "dayWindowStart": "2026-02-17T00:00:00Z"
}

liveauth_mcp_refresh

Renueva el token JWT sin volver a autenticarte. Usa el refreshToken devuelto por confirm para obtener un nuevo JWT cuando el actual expire.

Parámetros:

  • refreshToken (cadena): El refreshToken de la respuesta de confirm

Devuelve:

{
  "jwt": "eyJhbGc...",
  "expiresIn": 600,
  "remainingBudgetSats": 9985
}

Nota: Guarda el refreshToken de forma segura. Lo necesitarás para extender la sesión sin resolver un nuevo PoW ni realizar otro pago Lightning.

Ejemplo de uso

Autenticación PoW

  1. Llama a liveauth_mcp_start para obtener un desafío PoW y un quoteId
  2. Llama a liveauth_mcp_confirm con el quoteId; el servidor MCP resuelve su desafío en caché con el solucionador de paquete existente
  3. Los clientes avanzados aún pueden enviar una solución explícita (hash = sha256(projectPublicKey:challengeHex:nonce) donde hash < targetHex)
  4. Usa el JWT en el encabezado Authorization: Bearer <token> para las solicitudes de API
  5. Después de cada llamada genérica a la API, llama a liveauth_mcp_charge con un costo de llamada, u omítelo para usar el precio global MCP del proyecto
  6. Para herramientas MCP monetizadas, envuelve los manejadores con createMcpGate({ toolId }) o createMcpGate({ toolName }) para que cada llamada cree un evento de ingresos y un recibo firmado

Autenticación Lightning

  1. Llama a liveauth_mcp_start con forceLightning: true para obtener una factura Lightning
  2. Usa liveauth_mcp_lnurl (o consulta liveauth_mcp_status) para obtener la factura BOLT11
  3. Paga la factura usando tu nodo/billetera Lightning
  4. Consulta liveauth_mcp_status con el quoteId hasta que paymentStatus sea "paid"
  5. Llama a liveauth_mcp_confirm solo con el quoteId para recibir el JWT
  6. Usa el JWT con la medición genérica liveauth_mcp_charge o con la atribución de herramientas de pago del SDK

Flujo de autenticación

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  AI Agent       │────▶│  MCP Server     │────▶│  LiveAuth API   │
│                 │     │                 │     │                 │
│ 1. Start       │     │ /api/mcp/start  │     │ Returns PoW    │
│ 2. Solve PoW   │     │                 │     │ challenge       │
│ 3. Confirm     │     │ /api/mcp/confirm│     │ Returns JWT    │
│ 4. API calls   │     │                 │     │                 │
│ 5. Charge      │     │ /api/mcp/charge │     │ Meter usage    │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Los servidores de herramientas de pago usan el mismo JWT pero cobran a través de un endpoint atribuido:

Agent calls MCP tool
→ Tool server calls POST /api/mcp/tools/{toolId}/charge
  or POST /api/mcp/charge with toolName
→ LiveAuth validates JWT and budget
→ LiveAuth records gross / platform fee / net revenue and returns a signed receipt
→ Tool handler runs and returns the result

Flujo de paquete L402

LiveAuthCore admite paquetes L402 respaldados por Lightning para acceso MCP prepago. Compra un paquete, reclama el macarrón después del pago, luego inicia una sesión MCP en modo L402 y confírmala con ese macarrón.

# 1. Create a bundle invoice.
curl -X POST https://api.liveauth.app/api/public/l402/bundle/invoice \
  -H "Content-Type: application/json" \
  -d '{"publicKey":"la_pk_xxx","tier":"starter","agentId":"agent_abc"}'

# 2. After the invoice is paid, claim a macaroon.
curl -X POST https://api.liveauth.app/api/public/l402/bundle/claim \
  -H "Content-Type: application/json" \
  -d '{"publicKey":"la_pk_xxx","paymentHash":"payment_hash_from_step_1"}'

# 3. Start and confirm an MCP session with the macaroon.
curl -X POST https://api.liveauth.app/api/mcp/start \
  -H "X-LW-Public: la_pk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"forceL402":true}'

curl -X POST https://api.liveauth.app/api/mcp/confirm \
  -H "X-LW-Public: la_pk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"quoteId":"quote_id_from_step_3","macaroon":"macaroon_from_step_2"}'

Desarrollo

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/cli.js

Recursos

Licencia

MIT

Categorías: authentication · payments · lightning · l402 · bitcoin · pay-per-call · metering · agent-tools · anti-abuse · mcp-server · typescript

Contrato de ejecución de pago y diagnóstico (SDK 1.2.0)

La puerta valida la sesión, registra el cargo y luego invoca el manejador. La autorización más un intento de ejecución aceptado es facturable, incluida una excepción del manejador, tiempo de espera o cancelación después del cargo. No hay reembolso automático. El rechazo de entrada antes de la puerta y las denegaciones de cargo no consumen uso. Un evento de ingresos con estado Charged prueba la facturación, no la ejecución exitosa de la herramienta.

Registra la herramienta y mueve su ciclo de vida de Draft a Active antes de atender llamadas de pago. Borrador significa no publicada (tool_unpublished); Pausada u otros estados no activos devuelven tool_inactive. El descubrimiento público también requiere Visibility=Public, pero la visibilidad es separada del ciclo de vida: las herramientas activas privadas/internas pueden cobrarse. No hay una bandera de publicación separada ni una nueva restricción de visibilidad en este cambio. Las herramientas desconocidas o eliminadas devuelven HTTP 404 con JSON status=deny, reason=tool_not_found y la identidad de la herramienta proporcionada. El ciclo de vida de la herramienta registrada y las denegaciones de presupuesto mantienen HTTP 200 con status=deny.

RazónSignificado
tool_unpublishedLa herramienta está en Borrador.
tool_inactiveLa herramienta está Pausada o no activa.
tool_not_foundNo hay una herramienta no eliminada que coincida.
budget_exceededLa política de presupuesto existente rechazó el cargo.
rate_limitedDenegación de tarifa estructurada compatible con el SDK; el controlador de cargo MCP actual no emite esta razón ni aplica su configuración por minuto.
deniedRespaldo del SDK cuando la denegación no tiene razón. Los códigos de razón futuros desconocidos permanecen disponibles en el error del SDK.

gate.charge() devuelve denegaciones estructuradas con ok=false, incluidas respuestas de error HTTP JSON con status=deny. gate.invoke() y gate.gateTool() lanzan ChargeDeniedError con reason, code, toolName y toolId. Por compatibilidad, extiende BudgetExceededError (y LiveAuthMcpError); los nuevos manejadores deben inspeccionar reason en lugar de asumir que cada instancia significa agotamiento del presupuesto. Los fallos de autenticación HTTP, transporte y validación no relacionados mantienen su ruta de error existente. Los backends más antiguos pueden seguir devolviendo errores de herramienta desconocida en texto plano hasta que se actualicen.

En caso de fallo del manejador, la puerta lanza ToolExecutionError con charge, idempotencyKey y un cause no enumerable. Su mensaje público es genérico. Expón una lista de permitidos de campos de cargo: grossSats, revenueEventId, receipt firmado y la clave de idempotencia. Mantén isError=true en la respuesta MCP. No serialices ni registres la causa del error, el contexto del manejador con JWT ni metadatos arbitrarios. El payload/firma del recibo son artefactos de respuesta pública existentes y pueden devolverse. Un cargo exitoso puede no tener recibo; preserva esta distinción en lugar de inventar uno. Los metadatos de facturación no implican ejecución exitosa.

import { ChargeDeniedError, ToolExecutionError } from '@liveauth-labs/mcp-server';

try {
  return await gate.invoke(jwt, input, handler, {}, { idempotencyKey });
} catch (error) {
  if (error instanceof ToolExecutionError) {
    return {
      isError: true,
      content: [{ type: 'text', text: 'Tool execution failed after authorization' }],
      _meta: { liveauth: {
        billed: true,
        grossSats: error.charge.grossSats,
        revenueEventId: error.charge.revenueEventId,
        receipt: error.charge.receipt,
        idempotencyKey: error.idempotencyKey,
      } },
    };
  }
  if (error instanceof ChargeDeniedError) {
    // Map known reasons to a public response. Do not serialize error.details wholesale.
    throw error;
  }
  throw error;
}

Tres identificadores distintos

  • Recibo body.requestId: identificador de solicitud/correlación HTTP del servidor de LiveAuth para el cargo original registrado. Un reintento devuelve ese recibo original.
  • Recibo body.idempotencyKey: clave de reintento estable controlada por el llamador. La deduplicación se limita a la sesión del llamador, el proveedor y la herramienta registrada para el financiamiento del llamador; el financiamiento heredado del proveedor usa el proyecto y la herramienta pagadores.
  • InvokeWorks _meta.requestId: ID de correlación MCP/cliente, tomado de X-Request-Id o derivado del ID de solicitud JSON-RPC. InvokeWorks también lo usa como la clave de idempotencia de LiveAuth.

Por ejemplo, _meta.requestId="client-123", recibo body.idempotencyKey="client-123" y recibo body.requestId="server-456" son válidos juntos. El SDK acepta idempotencyKey; no envía una opción separada de ID de solicitud de cliente. El contexto del llamador { requestId } es contexto local del manejador. Usa una nueva clave para una nueva llamada lógica y reutiliza una clave solo para la misma operación prevista. El cobro deduplicado no almacena en caché los resultados del manejador: los reintentos pueden ejecutar el manejador nuevamente en el modo de proveedor heredado. Las autorizaciones duplicadas financiadas por el llamador devuelven el estado de pago registrado y no se ejecutan nuevamente. Las verificaciones de estado de la herramienta y de precio aún preceden a la deduplicación.