Construa um Servidor MCP com Pagamento Lightning em 10 Minutos

A dor

Você construiu uma ferramenta MCP que chama uma API paga em cada invocação. Cada agente que conhece a URL do seu servidor pode atacá-lo gratuitamente. O chamador educado com uma identidade Nostr real paga a mesma taxa que o bot que alguém criou uma hora atrás, ou seja, nada. Aqui está como parar isso, de ponta a ponta, com um servidor que você pode clonar e executar nos próximos dez minutos.

O que você vai construir

• Um servidor MCP em funcionamento com uma ferramenta, bitcoin_data, que busca BTC/USD mais taxas de mempool do mempool.space.
• Um portão de pagamento Lightning L402. A primeira chamada retorna 402 com uma fatura bolt11. Pague-a, tente novamente, obtenha os dados.
• Uma verificação de pontuação de Profundidade de Identidade em cima do pagamento. O chamador tem que pagar E ter uma reputação por pubkey acima do seu limite.

O L402 sozinho prova que um chamador pagou alguns sats. Adicionar a verificação de pontuação DoI prova que eles pagaram E têm uma reputação que sobrevive entre sessões e custa trabalho irreversível para falsificar. Essa segunda parte é a parte que a maioria dos kits de cobrança MCP ignora.

Pré-requisitos

• Node 18 ou mais recente.
• Uma instância LNBits contra a qual você pode gerar faturas. A testnet pública funciona bem para um teste rápido. Use a chave invoice/read, nunca a chave de administrador.
• Cerca de cinco minutos de atenção.

Passo 1. Clone o exemplo

git clone https://github.com/zekebuilds-lab/mcp-l402-gate-example
cd mcp-l402-gate-example
cp .env.example .env

Abra .env e preencha três valores:

• GATE_HMAC_SECRET. A chave HMAC que assina seus macaroons L402. Gere uma com openssl rand -hex 32. Rode-a periodicamente.
• LNBITS_URL. A URL base da sua carteira LNBits (por exemplo, https://your-lnbits-host.example).
• LNBITS_INVOICE_KEY. A chave invoice/read daquela carteira. A chave de administrador também funcionaria, mas não deveria. Use a chave de fatura.

PORT padrão é 3100 e ORACLE_URL padrão é o oracle público PowForge em https://identity.powforge.dev. Deixe ambos inalterados, a menos que você tenha um motivo.

Passo 2. Instale e inicie

npm install
npm start

Você deve ver algo como:

mcp-l402-gate-example listening on :3100
oracle: https://identity.powforge.dev
tool:   POST http://localhost:3100/tools/bitcoin_data

Se você ver reclamações sobre LNBITS_URL, seu .env não foi carregado. Confirme que o arquivo está na raiz do repositório e que as chaves não estão entre aspas.

Passo 3. Teste o portão

A primeira chamada não tem autenticação. O portão retorna 402 com uma fatura bolt11 tanto no corpo quanto no cabeçalho padrão WWW-Authenticate:

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

Resposta esperada:

HTTP/1.1 402 Pagamento Necessário
WWW-Authenticate: L402 macaroon="...", invoice="lnbc1..."
Content-Type: application/json

{
  "error": "pagamento necessário",
  "macaroon": "...",
  "invoice": "lnbc1...",
  "payment_hash": "..."
}

Pague essa invoice com qualquer carteira Lightning, capture a pré-imagem, e então tente novamente com o cabeçalho de Autorização L402:

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

Você receberá de volta o preço BTC/USD, as estimativas atuais de taxas de mempool e a pontuação DoI do chamador na carga útil da resposta. O macaroon é de uso único, então uma tentativa de repetição com a mesma pré-imagem recebe um 409.

Como funciona a pontuação de identidade

O chamador afirma uma pubkey Nostr através do cabeçalho X-Caller-Pubkey. O middleware verifica essa pubkey contra o oracle público DoI em identity.powforge.dev e recebe de volta um certificado assinado por Schnorr: uma pontuação composta mais quatro sub-dimensões (social, acesso, garantia, econômica) todas ancoradas a um bloco específico da cadeia Bitcoin.

Se MIN_SCORE é 0, pagar é suficiente. Se você definir como 10, o chamador deve superar o nível emergente. Defina como 40 se sua ferramenta consumir GPU real. Defina como 100 se tiver efeitos colaterais caros. Os limites mapeiam para os buckets de classificação publicados pelo oracle, então você pode decidir com base no que seu manipulador realmente custa.

Uma carteira nova paga os mesmos sats que um chamador de longa duração, mas uma pubkey nova pontua zero no oracle e é rejeitada antes que o corpo da ferramenta seja executado. Sybils ainda pagam o pedágio, mas o pedágio mais a exigência de reputação por pubkey é mais difícil de moer do que qualquer uma das partes sozinha.

Indo para produção

Referência completa de configuração, a variante middleware Express e o wrapper da ferramenta MCP estão em powforge.dev/mcp. O envelope de pontuação do oracle, os limites de classificação e o formato de âncora da chaintip estão documentados lá também.

Se você está pesando isso contra outros kits de cobrança MCP (sats4ai-mcp, invinoveritas, l402-kit, 402-mcp, coinopai-mcp), eu escrevi uma comparação lado a lado em powforge.dev/mcp/compare/sats4ai/. Versão curta: cada um deles envia o transporte L402 corretamente. A parte que está faltando em todos eles é a identidade. A identidade é o que torna o portão difícil de moer.

Fechar

Se você configurar um servidor com isso e ele fizer algo interessante, coloque a URL nos comentários. Eu irei pagar uma fatura e ler a resposta.

Divulgação