LiveAuth MCP Server

Prova de Trabalho + autenticação via Lightning Network para agentes de IA. Encapsula ferramentas MCP pagas com recibos assinados via L402.

GitHub
1
Experimente este MCPPatrocinado

Documentação

LiveAuth MCP Server

MCP financiado pelo chamador (1.3.0): use o createMcpGate({ publicKey, toolName, fundingMode: 'caller' }) existente. O LiveAuthCore verifica o pagamento do chamador e é responsável pela contabilidade; este pacote é responsável pelos desafios de pagamento, vinculação de tentativas e prevenção de execução duplicada. Financiamento do chamador, exemplos de API e migração. PoW autentica; não financia ferramentas pagas.

npm version MIT license L402 MCP

Autenticação, medição de pagamento por chamada e recibos assinados para agentes de IA e ferramentas MCP: nativo em Bitcoin, com suporte a Lightning e compatível com L402.

Este servidor MCP permite que qualquer agente de IA autentique-se na sua API usando prova de trabalho (gratuita, sem conta) ou micropagamentos via Lightning Network (sats), e então meça e monetize chamadas subsequentes de ferramentas com preço por chamada, eventos de receita idempotentes e recibos assinados com HMAC que auditores podem verificar offline.

Use quando quiser:

  • Proteger uma API ou ferramenta MCP com custo real de computação ou sats reais (anti-spam por design, não por CAPTCHA).
  • Cobrar agentes de IA por chamada sem exigir cadastro de conta.
  • Emitir uma trilha de auditoria à prova de adulteração (mcp-call-receipt-v1 assinado) para cada invocação paga de ferramenta.
  • Oferecer acesso a pacotes L402 com suporte a Lightning para sessões MCP pré-pagas.

Experimente em 5 segundos — sem conta, sem chave de API:

npx @liveauth-labs/mcp-server

Sem configuração, o servidor usa o projeto demo anônimo do LiveAuth e o fluxo PoW real. Adicione LIVEAUTH_API_KEY somente quando precisar da política, preço ou atribuição de um projeto específico.

Ferramentas Disponíveis (descoberta automática via Glama / MCP)

FerramentaFinalidade
liveauth_mcp_startIniciar uma sessão. Retorna um desafio PoW, uma fatura Lightning ou uma dica de pacote L402.
liveauth_mcp_confirmEnviar um desafio PoW resolvido, uma fatura Lightning paga ou um macaroon L402 → receber um JWT.
liveauth_mcp_chargeMedir o uso após uma chamada. Com toolName, resolve o preço da ferramenta registrada e registra um evento de receita pago.
liveauth_mcp_refreshTrocar um token de atualização por um novo JWT — sem necessidade de reautenticação.
liveauth_mcp_statusConsultar o status da sessão/pagamento (confirmação Lightning, expiração).
liveauth_mcp_lnurlBuscar a fatura BOLT11 de uma sessão (compatível com lnget).
liveauth_mcp_payment_confirmConfirmar um pagamento do chamador com a sessão atual; depois, tentar novamente a operação original.
liveauth_mcp_usageConsultar orçamento restante, chamadas usadas e janelas de limite de taxa.

Esquemas completos de parâmetros e respostas estão na Referência de Ferramentas abaixo.

Início Rápido em 5 Minutos

Opção 1 — PoW sem credenciais (sem conta, sem chave, sem carteira)

npx @liveauth-labs/mcp-server

Em um cliente MCP, chame liveauth_mcp_start e depois liveauth_mcp_confirm apenas com o quoteId retornado. O pacote reutiliza seu solucionador PoW existente localmente e a API LiveAuth verifica o desafio assinado antes de emitir um JWT de sessão de curta duração.

Opção 2 — Modo de Produção

  1. Obtenha uma chave de API em liveauth.app.
  2. Adicione ao claude_desktop_config.json do 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. Reinicie o Claude. Pronto.

Opção 3 — Programático (CLI / SDK)

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

O pacote também é um SDK TypeScript — veja Uso do SDK abaixo. O binário CLI é liveauth-mcp.

Por que LiveAuth?

Para provedores de API / desenvolvedores de ferramentas:

  • Pare bots na camada de protocolo. PoW e sats Lightning não são reproduzíveis, não são phishing e não exigem contas de usuário.
  • Cobre por chamada em sats. Assinamos um recibo que você pode mostrar a auditores, clientes ou contadores.
  • Envolva qualquer ferramenta MCP com uma linha (createMcpGate) e obtenha receita por ferramenta, preço mínimo/máximo por ferramenta e tentativas idempotentes.

Para agentes de IA / construtores de agentes:

  • Acesso sem permissão a APIs pagas — resolva um PoW ou pague sats, receba um JWT. Sem cadastro, sem e-mail, sem dança OAuth.
  • Use PoW, faturas Lightning ou macaroons de pacote L402 para acesso de agentes.
  • Projetos podem liquidar por meio de um nó Lightning personalizado quando configurado; caso contrário, os pagamentos usam o nó configurado pelo LiveAuthCore.

A matemática que importa: se sua ferramenta está sendo raspada por um bot, cobrar 1 sat por chamada é suficiente para tornar o raspador não lucrativo. Chamamos isso de economia de custo de ataque, e é a razão de existirmos.

Instalação

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

Ou use diretamente com npx:

npx @liveauth-labs/mcp-server

Goose

O LiveAuth para Goose usa o mesmo servidor MCP stdio baseado em padrões que todos os outros clientes — não há wrapper Goose, daemon ou runtime de autenticação duplicado.

Instalar no Goose

Ou imprima o deep link oficial e os fallbacks atuais:

npx @liveauth-labs/mcp-server setup goose

Para uma sessão CLI Goose avulsa:

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

Configuração manual stdio do Goose, quando o deep link não estiver disponível:

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

Não edite uma configuração Goose existente de forma destrutiva. Prefira o deep link ou goose configure; se você adicionar configuração de projeto posteriormente, insira-a pelas configurações secretas de extensão do Goose, em vez de YAML de texto simples compartilhado.

Teste rápido do Goose

Pergunte ao Goose:

Use o LiveAuth para iniciar o fluxo de autenticação padrão. Confirme a cotação retornada e depois mostre meu uso do LiveAuth.

O fluxo inicial usa o desafio PoW do projeto demo anônimo e não requer carteira. Uma chave pública de projeto é opcional:

VariávelQuando definir
LIVEAUTH_API_KEYPolítica, preço e atribuição específicos do projeto.
LIVEAUTH_API_BASEUma API LiveAuth auto-hospedada em vez de https://api.liveauth.app.
LIVEAUTH_DEMO=trueOptar explicitamente pela demo Lightning simulada localmente mais antiga.

Quando um fluxo pago é solicitado, os resultados da ferramenta mantêm os campos de fatura existentes e também incluem dados estruturados portáveis:

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

Clientes com suporte a MCP Apps podem renderizar o QR incluído, ação de abrir carteira, expiração e estado pago/pendente/expirado em tempo real. Outros clientes recebem o JSON e o conteúdo da imagem QR como resultados MCP comuns.

Solução de problemas do Goose

  • Se o link não abrir, execute npx @liveauth-labs/mcp-server setup goose e use o fallback de sessão única ou manual.
  • Se npx não estiver disponível, instale uma versão atual do Node.js (Node 18 ou mais recente).
  • Se uma chave de projeto fornecida for rejeitada, remova-a para verificar o fluxo PoW anônimo; chaves inválidas e revogadas intencionalmente não fazem fallback para demo.
  • Se uma fatura Lightning expirar, chame liveauth_mcp_start novamente para obter uma cotação nova.
  • Mantenha tokens de atualização e quaisquer credenciais não públicas fora de logs e configuração em texto simples.

O LiveAuth permite que agentes adquiram autorização em tempo de execução, em vez de exigir que cada ferramenta seja provisionada com credenciais permanentes antecipadamente.

Uso do SDK

O pacote também pode ser importado como SDK TypeScript/JavaScript. Importar o pacote não inicia o servidor MCP stdio; o CLI está no binário liveauth-mcp.

Auxiliar de Autenticação do 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);

O cliente armazena JWTs confirmados, atualiza-os antes da expiração quando um token de atualização é retornado e expõe o token atual por meio de liveauth.token. Chame liveauth.destroy() quando seu aplicativo estiver encerrando para limpar o estado do token e os temporizadores de atualização.

Para PoW, config.publicKey é a credencial enviada em X-LW-Public. Pode ser a chave pública primária do projeto ou uma chave pública de API ativa pertencente a esse projeto. A API retorna a chave canônica do projeto em session.powChallenge.projectPublicKey; o solucionador faz hash dessa chave retornada, e a confirmação ainda envia a credencial configurada. Essas duas strings de chave podem legitimamente diferir, então compará-las por igualdade não é uma verificação de isolamento de projeto.

Use sessões do seu endpoint de API LiveAuth confiável. O servidor vincula a cotação e o desafio assinado ao projeto resolvido e emite um JWT com projectId e authType. Para diagnóstico, compare o projectId do JWT com o ID de projeto esperado do seu console, sem registrar o token. Decodificar claims sozinho não verifica a assinatura de um JWT.

Para exigir uma fatura paga 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);

Auxiliar de Portão do 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 o JWT, cobra o custo em sats configurado ou o padrão do projeto no backend e passa context.liveAuth para o seu handler. O nome mais antigo gate.gateTool(...) ainda é suportado.

Atribuição de Ferramenta Paga

Se o seu servidor MCP tiver um ID de ferramenta LiveAuth registrado, passe toolId ao criar o portão. As cobranças então vão para:

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

em vez do endpoint genérico legado:

POST /api/mcp/charge

Você também pode passar um slug/nome de ferramenta registrado como toolName. Nesse modo, as cobranças vão para o endpoint genérico com identidade de ferramenta no corpo:

POST /api/mcp/charge

As cobranças de ferramenta preservam as mesmas verificações de orçamento de sessão, mas também registram um evento de receita imutável com sats brutos, taxa de plataforma LiveAuth, sats líquidos do desenvolvedor, nome do método da ferramenta, projeto/sessão/token pagante, metadados e chave de idempotência. Quando costSats é omitido, o LiveAuthCore usa o preço padrão da ferramenta registrada; sem toolId ou toolName, ele usa o preço MCP global do projeto.

Ferramentas registradas também podem ter uma URL de webhook de chamada paga. Em cada nova chamada paga bem-sucedida, o LiveAuthCore enfileira um webhook liveauth.mcp.tool.paid_call com a identidade da ferramenta, sats brutos/plataforma/líquidos, ID do evento de receita, metadados e o recibo assinado. Se a URL do webhook da ferramenta estiver em branco, o LiveAuthCore usa a URL do webhook do projeto; tentativas idempotentes não enfileiram duplicatas.

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,
    },
  }
);

Quando toolId ou toolName está definido, GateToolOptions suporta:

OpçãoFinalidade
costSatsSats opcionais a cobrar por esta chamada. Omita para usar o preço da ferramenta registrada ou o preço global do projeto.
toolNameSlug/nome de ferramenta opcional por chamada ao usar o endpoint genérico.
toolMethodNameMétodo dentro da ferramenta, como web_fetch ou search.
idempotencyKeyChave segura para tentativas. Reutilizá-la para a mesma ferramenta retorna o evento de receita original e o recibo assinado em vez de cobrar duas vezes.
agentIdIdentificador opcional de chamador/agente para relatórios.
metadataPequeno objeto JSON para contexto de auditoria. Não armazene saída privada da ferramenta aqui.

As respostas de cobrança de ferramenta incluem os contadores de orçamento normais mais a contabilidade de receita:

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

O recibo é um artefato de auditoria assinado por chamada retornado pelo LiveAuthCore para cobranças pagas de ferramentas. Armazene-o com o resultado da sua ferramenta quando precisar de prova de cobrança ou reconciliação posterior.

Se nenhum toolId ou toolName estiver configurado, o SDK continua usando /api/mcp/charge para medição de uso compatível com versões anteriores.

Configuração

Claude Desktop

Adicione ao seu 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 sem credenciais: Se você omitir LIVEAUTH_API_KEY, o servidor chama os endpoints MCP normais sem cabeçalho de projeto. O LiveAuth vincula seu projeto demo anônimo configurado, retorna um desafio PoW assinado e preserva verificação normal, JWT, limite de taxa e limites de medição. LIVEAUTH_DEMO=true permanece como opt-in explícito para a prévia Lightning simulada localmente mais antiga.

Outras variáveis de ambiente:

VariávelPadrãoFinalidade
LIVEAUTH_API_KEY(não definido)Sua chave pública de projeto LiveAuth (la_pk_…).
LIVEAUTH_API_BASEhttps://api.liveauth.appSubstituição para LiveAuth auto-hospedado.
LIVEAUTH_DEMOfalseUsar explicitamente a demo Lightning simulada localmente legada.

Outros Clientes MCP

O servidor fala stdio (JSON-RPC 2.0). Inicie com:

liveauth-mcp

Também funciona com qualquer cliente compatível com MCP: Cursor, VS Code, ChatGPT, Windsurf, Continue, Cline.

Referência de Ferramentas

Esquemas completos para cada ferramenta MCP. Cada ferramenta é compatível com JSON-RPC 2.0 e testada sob src/index.test.ts e src/cli.test.ts.

liveauth_mcp_start

Iniciar uma nova sessão MCP LiveAuth. Retorna um desafio PoW por padrão, ou uma fatura Lightning se forceLightning=true. Parâmetros:

  • forceLightning (booleano, opcional): Se verdadeiro, solicita fatura Lightning em vez de desafio PoW
  • forceL402 (booleano, opcional): Se verdadeiro, inicia uma sessão que deve ser confirmada com um macaroon de bundle L402

Retornos (PoW):

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

Retornos (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"
  }
}

Retornos (bundle L402):

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

liveauth_mcp_confirm

Envie um desafio de prova de trabalho resolvido, deixe o pacote resolver seu desafio em cache, consulte um pagamento Lightning ou apresente um macaroon L402 para receber um token de autenticação JWT.

Parâmetros:

  • quoteId (string): O quoteId da resposta de início
  • challengeHex (string, opcional, somente PoW): O hex do desafio da resposta de início
  • nonce (número, opcional, somente PoW): O nonce que resolve o desafio PoW
  • hashHex (string, opcional, somente PoW): O hash resultante (sha256 de projectPublicKey:challengeHex:nonce)
  • expiresAtUnix (número, opcional, somente PoW): Carimbo de data/hora de expiração do desafio
  • difficultyBits (número, opcional, somente PoW): Bits de dificuldade do desafio
  • signature (string, opcional, somente PoW): Assinatura do desafio
  • macaroon (string, somente L402): Macaroon de bundle retornado do fluxo de reivindicação de bundle L402

Quando o desafio veio deste servidor MCP, chamar confirm com quoteId sozinho reutiliza o solucionador PoW existente do pacote. Campos de solução explícitos permanecem suportados para compatibilidade.

Retornos:

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

Nota: Armazene o refreshToken com segurança. Ele é retornado nos dados da ferramenta MCP, mas nunca é gravado em stderr ou logs de aplicação. Use liveauth_mcp_refresh para obter um novo JWT sem reautenticar.

liveauth_mcp_charge

Meça o uso da API após fazer uma chamada autenticada. O servidor MCP integrado chama o endpoint genérico /api/mcp/charge. Fornecer toolName permite que o LiveAuth resolva uma ferramenta registrada, aplique seu preço configurado e crie um evento de receita de ferramenta paga; omitir toolName mantém a medição genérica compatível com versões anteriores.

Parâmetros:

  • callCostSats (número, opcional): Custo da chamada de API em sats. Omita para usar o preço do backend.
  • toolName (string, opcional): Slug/nome da ferramenta MCP registrada para preço e atribuição por ferramenta.

Retornos:

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

Se o orçamento for excedido:

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

liveauth_mcp_status

Verifique o status de uma sessão MCP. Use para consultar a confirmação de pagamento Lightning.

Parâmetros:

  • quoteId (string): O quoteId da resposta de início

Retornos:

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

Quando paymentStatus for "paid", a sessão está confirmada. Chame liveauth_mcp_confirm novamente para obter o JWT.

liveauth_mcp_lnurl

Obtenha a fatura Lightning para uma sessão (compatível com lnget). Use para recuperar a fatura BOLT11 para pagamento com qualquer carteira Lightning.

Parâmetros:

  • quoteId (string): O quoteId da resposta de início

Retornos:

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

Nota: Isso é compatível com lnget e outras ferramentas de pagamento Lightning. Use para consultar a fatura quando liveauth_mcp_confirm retornar "payment pending".

liveauth_mcp_usage

Consulte o uso atual e o orçamento restante sem fazer uma cobrança. Use para verificar o status antes de fazer chamadas de API.

Parâmetros: (nenhum obrigatório)

Retornos:

{
  "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

Atualize o token JWT sem reautenticar. Use o refreshToken retornado de confirm para obter um novo JWT quando o atual expirar.

Parâmetros:

  • refreshToken (string): O refreshToken da resposta de confirm

Retornos:

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

Nota: Salve o refreshToken com segurança. Você precisará dele para estender a sessão sem resolver um novo PoW ou fazer outro pagamento Lightning.

Exemplo de Uso

Autenticação PoW

  1. Chame liveauth_mcp_start para obter um desafio PoW e quoteId
  2. Chame liveauth_mcp_confirm com o quoteId; o servidor MCP resolve seu desafio em cache com o solucionador de pacote existente
  3. Clientes avançados ainda podem enviar uma solução explícita (hash = sha256(projectPublicKey:challengeHex:nonce) onde hash < targetHex)
  4. Use o JWT no cabeçalho Authorization: Bearer <token> para solicitações de API
  5. Após cada chamada de API genérica, chame liveauth_mcp_charge com um custo de chamada, ou omita para usar o preço global MCP do projeto
  6. Para ferramentas MCP monetizadas, envolva os manipuladores com createMcpGate({ toolId }) ou createMcpGate({ toolName }) para que cada chamada crie um evento de receita e recibo assinado

Autenticação Lightning

  1. Chame liveauth_mcp_start com forceLightning: true para obter uma fatura Lightning
  2. Use liveauth_mcp_lnurl (ou consulte liveauth_mcp_status) para obter a fatura BOLT11
  3. Pague a fatura usando seu nó/carteira Lightning
  4. Consulte liveauth_mcp_status com o quoteId até que paymentStatus seja "paid"
  5. Chame liveauth_mcp_confirm apenas com o quoteId para receber o JWT
  6. Use o JWT com medição genérica liveauth_mcp_charge ou atribuição de ferramenta paga do SDK

Fluxo de Autenticação

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  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    │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Servidores de ferramentas pagas usam o mesmo JWT, mas cobram por meio de um endpoint atribuído:

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

Fluxo de Bundle L402

O LiveAuthCore suporta bundles L402 com suporte Lightning para acesso MCP pré-pago. Compre um bundle, reivindique o macaroon após o pagamento, inicie uma sessão MCP no modo L402 e confirme com esse macaroon.

# 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"}'

Desenvolvimento

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/cli.js

Recursos

Licença

MIT

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

Contrato de execução paga e diagnóstico (SDK 1.2.0)

O gate valida a sessão, registra a cobrança e então invoca o manipulador. Autorização mais uma tentativa de execução aceita é cobrável, incluindo uma exceção do manipulador, timeout ou cancelamento após a cobrança. Não há reembolso automático. Rejeição de entrada antes do gate e negações de cobrança não consomem uso. Um evento de receita com status Charged prova a cobrança, não a execução bem-sucedida da ferramenta.

Registre a ferramenta e mova seu ciclo de vida de Draft para Active antes de servir chamadas pagas. Rascunho significa não publicado (tool_unpublished); Pausado ou outros estados não ativos retornam tool_inactive. A descoberta pública também requer Visibility=Public, mas a visibilidade é separada do ciclo de vida: ferramentas ativas privadas/internas podem ser cobradas. Não há flag de publicação separado ou nova restrição de visibilidade nesta mudança. Ferramentas desconhecidas ou removidas retornam HTTP 404 com JSON status=deny, reason=tool_not_found e a identidade da ferramenta fornecida. O ciclo de vida da ferramenta registrada e negações de orçamento mantêm HTTP 200 com status=deny.

MotivoSignificado
tool_unpublishedA ferramenta está em Rascunho.
tool_inactiveA ferramenta está Pausada ou não ativa.
tool_not_foundNenhuma ferramenta correspondente não removida.
budget_exceededA política de orçamento existente rejeitou a cobrança.
rate_limitedNegação de taxa estruturada suportada pelo SDK; o controlador de cobrança MCP atual não emite esse motivo nem aplica sua configuração por minuto.
deniedFallback do SDK quando a negação não tem motivo. Códigos de motivo futuros desconhecidos permanecem disponíveis no erro do SDK.

gate.charge() retorna negações estruturadas com ok=false, incluindo respostas de erro HTTP JSON com status=deny. gate.invoke() e gate.gateTool() lançam ChargeDeniedError com reason, code, toolName e toolId. Para compatibilidade, ele estende BudgetExceededError (e LiveAuthMcpError); novos manipuladores devem inspecionar reason em vez de assumir que toda instância significa esgotamento de orçamento. Falhas não relacionadas de autenticação HTTP, transporte e validação mantêm seu caminho de erro existente. Backends mais antigos podem ainda retornar erros de ferramenta desconhecida em texto simples até serem atualizados.

Em falha do manipulador, o gate lança ToolExecutionError com charge, idempotencyKey e um cause não enumerável. Sua mensagem pública é genérica. Exponha uma lista de permissões de campos de cobrança: grossSats, revenueEventId, receipt assinado e a chave de idempotência. Mantenha isError=true na resposta MCP. Não serialize nem registre a causa do erro, o contexto do manipulador com JWT ou metadados arbitrários. Payload/assinatura do recibo são artefatos de resposta pública existentes e podem ser retornados. Uma cobrança bem-sucedida pode não ter recibo; preserve essa distinção em vez de inventar um. Metadados de cobrança não implicam execução bem-sucedida.

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;
}

Três identificadores distintos

  • Recibo body.requestId: identificador de solicitação/correlação HTTP do servidor do LiveAuth para a cobrança original registrada. Uma nova tentativa retorna esse recibo original.
  • Recibo body.idempotencyKey: chave de nova tentativa estável controlada pelo chamador. A deduplicação é limitada à sessão do chamador, provedor e ferramenta registrada para financiamento do chamador; financiamento legado do provedor usa projeto pagante e ferramenta.
  • InvokeWorks _meta.requestId: ID de correlação MCP/cliente, obtido de X-Request-Id ou derivado do ID de solicitação JSON-RPC. InvokeWorks também o usa como chave de idempotência do LiveAuth.

Por exemplo, _meta.requestId="client-123", recibo body.idempotencyKey="client-123" e recibo body.requestId="server-456" são válidos juntos. O SDK aceita idempotencyKey; ele não envia uma opção separada de ID de solicitação do cliente. Contexto do chamador { requestId } é contexto local do manipulador. Use uma nova chave para uma nova chamada lógica e reutilize uma chave apenas para a mesma operação pretendida. Cobrança deduplicada não armazena em cache resultados do manipulador: novas tentativas podem executar o manipulador novamente no modo de provedor legado. Autorizações duplicadas financiadas pelo chamador retornam status de pagamento registrado e não executam novamente. Verificações de estado da ferramenta e preço ainda precedem a deduplicação.