Receita: servidor MCP pago

Os agentes não precisam pagar por conta própria. Uma pessoa compra um pacote de créditos no navegador e depois cada chamada de ferramenta consulta o saldo, desconta créditos com uma chave de idempotência e trabalha. Quando não há créditos, a ferramenta responde com um link de recarga que o agente mostra à pessoa. Sem x402, sem carteira no agente, sem cobranças automáticas.

Como funciona

1. 1

   Um pacote de créditos

   Como em créditos de API. Dê um preço a cada ferramenta e escreva-o na descrição dela.

2. 2

   Quem chama

   Um servidor hospedado associa a chave de API de cada assinante ao external_id de um cliente. PERLY_PAY_SECRET_KEY fica só no seu servidor.

3. 3

   Primeiro descontar, depois trabalhar

   credits.consume com o nome da ferramenta como action e uma chave nova que o seu servidor gera a cada chamada; depois o trabalho.

4. 4

   Não deu?

   Devolva um resultado de ferramenta com isError: true e o link de recarga, não um erro de protocolo: os clientes mostram isso.

5. 5

   Ajudantes grátis

   Ferramentas balance e top_up, para o agente poder explicar o que acontece.

server.registerTool("summarize", { description: "Costs 3 credits.", inputSchema: { text: z.string() } }, async ({ text }, extra) => {
  const refused = await charge(userId, 3, "summarize", extra.requestId); // credits.consume, or a top-up message
  if (refused) return { isError: true, content: [{ type: "text", text: refused }] };
  return { content: [{ type: "text", text: summarize(text) }] };
});

Execute o exemplo

1. 1

   Instale

   npm install em examples/paid-mcp-server (Node 20.12+).

2. 2

   Chave

   Copie .env.example para .env e coloque uma chave de teste (sk_test_…) em PERLY_PAY_SECRET_KEY.

3. 3

   Prepare

   npm run setup cria o produto e o preço com a sua chave e imprime os ids deles para o .env.

4. 4

   Execute

   npm start (ou npm run dev), como diz o README dele.

5. 5

   Pague sem carteira

   Adicione ao Claude Code (claude mcp add paid-tools -- npx tsx "$PWD/src/server.ts") e execute word_stats: a resposta é a página de recarga. Escolha um pacote, clique em Simulate payment e execute de novo.

Erros comuns

• PERLY_PAY_SECRET_KEY numa configuração MCP que outros copiam. Hospede o servidor você mesmo ou faça-o chamar o seu backend.
• Descontar depois do trabalho: um desconto que falha significa trabalho grátis.
• Tirar a chave do desconto do id do JSON-RPC: quem escolhe é o cliente, e o mesmo id devolve o primeiro desconto, então a ferramenta trabalha de novo de graça.