# Przepis: płatny serwer MCP

> Pobieraj opłatę za narzędzia serwera MCP za każde wywołanie — w kredytach. Człowiek raz kupuje pakiet; każde wywołanie najpierw pobiera, potem działa.

Agenci nie powinni płacić sami. Człowiek kupuje pakiet kredytów w przeglądarce, a potem każde wywołanie narzędzia sprawdza saldo, pobiera kredyty z kluczem idempotencji i działa. Gdy kredytów brak, narzędzie odpowiada linkiem do doładowania, który agent pokazuje człowiekowi. Bez x402, bez portfela w agencie, bez automatycznego pobierania.

> **Uwaga:** Z asystentem: ten przepis realizuje w Twoim projekcie skill `paid-mcp-tools` wtyczki Perly Pay. Działający przykład to `examples/paid-mcp-server` (MIT) w repozytorium wtyczki.

## Jak to działa

1. **Pakiet kredytów** — Jak w [kredytach API](https://pay.perly.io/docs/recipe-api-credits.md). Daj każdemu narzędziu cenę i napisz ją w jego opisie.
2. **Kto wywołuje** — Hostowany serwer przypisuje klucz API każdego abonenta do `external_id` klienta. `PERLY_PAY_SECRET_KEY` jest tylko na Twoim serwerze.
3. **Najpierw pobierz, potem pracuj** — `credits.consume` z nazwą narzędzia jako `action` i nowym kluczem, który Twój serwer tworzy dla każdego wywołania, potem praca.
4. **Brakuje?** — Zwróć wynik narzędzia z `isError: true` i linkiem do doładowania, a nie błąd protokołu: klienci go pokazują.
5. **Darmowi pomocnicy** — Narzędzia `balance` i `top_up`, żeby agent mógł wyjaśnić, co się dzieje.

**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) }] };
});
```

## Uruchom przykład

1. **Zainstaluj** — `npm install` w `examples/paid-mcp-server` (Node 20.12+).
2. **Klucz** — Skopiuj `.env.example` do `.env` i wpisz klucz testowy (`sk_test_…`) w `PERLY_PAY_SECRET_KEY`.
3. **Przygotuj** — `npm run setup` tworzy produkt i cenę Twoim kluczem i drukuje ich identyfikatory do `.env`.
4. **Uruchom** — `npm start` (lub `npm run dev`), jak mówi jego README.
5. **Zapłać bez portfela** — Dodaj go do Claude Code (`claude mcp add paid-tools -- npx tsx "$PWD/src/server.ts"`), uruchom `word_stats`: odpowiedzią jest strona doładowania. Wybierz pakiet, kliknij **Simulate payment** i uruchom ponownie.

## Pułapki

- `PERLY_PAY_SECRET_KEY` w konfiguracji MCP, którą kopiują inni. Hostuj serwer u siebie albo niech łączy się z Twoim backendem.
- Pobieranie po pracy: nieudane pobranie oznacza wtedy darmową pracę.
- Klucz pobrania z identyfikatora JSON-RPC: wybiera go klient, a ten sam identyfikator zwraca pierwsze pobranie, więc narzędzie znowu działa za darmo.