> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solvapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> SolvaPay quick facts:
> - REST API base URL: https://api.solvapay.com. All public endpoints are under /v1/sdk/ (for example GET https://api.solvapay.com/v1/sdk/products). Sandbox and production share this URL.
> - Auth: send a secret key as `Authorization: Bearer <secret key>` (the REST API also accepts `X-API-Key: <secret key>`).
> - Secret key prefixes: `sk_sandbox_` (sandbox, test payments) and `sk_live_` (production). The prefix selects the environment.
> - Get keys in SolvaPay Console (https://app.solvapay.com) > Developers > API Keys. Use a sandbox key while building.
> - Admin MCP Server: https://mcp.solvapay.com/mcp (Streamable HTTP). Connect with OAuth: add the URL and sign in with the SolvaPay account; no API key needed. OAuth sessions use the live account; for sandbox data or headless clients, send `Authorization: Bearer <secret key>` (X-API-Key is ignored).
> - Install the SolvaPay agent skills: `npx skills add https://solvapay.com` (skills CLI older than 1.5.7: `npx skills add solvapay/skills`).
> - TypeScript SDK setup: `npx solvapay@latest init`. The SDK reads SOLVAPAY_SECRET_KEY and defaults to https://api.solvapay.com.
> - Plans take an options[] array (billingCycle, charge, limit, ...). Retired plan fields price, freeUnits and billingCycle are rejected.
> - Step-by-step from zero to a first paid call: Managed MCP https://docs.solvapay.com/build/managed-mcp.md, TypeScript SDK https://docs.solvapay.com/build/typescript-sdk.md, agent skill https://docs.solvapay.com/build/agent-skill.md.
> - Details: https://docs.solvapay.com/api-reference/authentication.md. OpenAPI spec: https://docs.solvapay.com/api-reference/openapi.json.

# September 18, 2026

> A code-declared free allowance for MCP tools, a free-capped scaffolder tier, and paywallReason coverage for limit_reached.

## Free allowance for MCP tools

`@solvapay/mcp` adds `registerFree` for an otherwise-free MCP tool with a per-customer cap
declared in code. Exhaustion uses the same paywall gate as a paid tool
(`paywallReason: 'limit_reached'`). Tools that name the same `free-*` meter share one allowance.
Unidentified callers fail with `401` / `identity_required` — there is no anonymous bucket.

* The cap lives next to the tool. There is no Console control for it.
* `remaining` / `used` / `limit` on the limits response are reused; the meter name tells you
  whether the remainder is included or a free allowance.
* Managed MCP public tools ("No plan") stay unlimited and untracked. A per-customer tracked cap
  is the TypeScript SDK path.
* `create-solvapay` accepts a `free-capped` operation tier that emits `ctx.registerFree`.
  `describe.mjs` still suggests `free` / `paid` / `skip` — a cap is a pricing decision you upgrade
  to.

See [Add a free allowance to MCP tools](https://docs.solvapay.com/sdks/typescript/guides/free-allowance.md),
the [MCP guide](https://docs.solvapay.com/sdks/typescript/guides/mcp.md), and
[Plans and billing glossary](https://docs.solvapay.com/plans/glossary.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.