# Receita: servidor MCP pago

> Cobre por cada chamada às ferramentas de um servidor MCP, com créditos. Uma pessoa compra um pacote uma vez; cada chamada primeiro desconta e depois trabalha.

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.

> **Nota:** Com um assistente: a skill `paid-mcp-tools` do plugin do Perly Pay faz esta receita no seu projeto. O exemplo executável é `examples/paid-mcp-server` (MIT) no repositório do plugin.

## Como funciona

1. **Um pacote de créditos** — Como em [créditos de API](https://pay.perly.io/docs/recipe-api-credits.md). Dê um preço a cada ferramenta e escreva-o na descrição dela.
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. **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. **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. **Ajudantes grátis** — Ferramentas `balance` e `top_up`, para o agente poder explicar o que acontece.

**A paid tool**

```js
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. **Instale** — `npm install` em `examples/paid-mcp-server` (Node 20.12+).
2. **Chave** — Copie `.env.example` para `.env` e coloque uma chave de teste (`sk_test_…`) em `PERLY_PAY_SECRET_KEY`.
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. **Execute** — `npm start` (ou `npm run dev`), como diz o README dele.
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.