# MCP-server

Claude, ChatGPT en andere MCP-clients koppelen aan Cijfr via OAuth. De server kan alleen wat jij mag, en verstuurde facturen blijven onaantastbaar.

## Verbinden

De MCP-server draait op `https://api.cijfr.com/api/mcp` (Streamable HTTP, JSON-RPC). Clients die OAuth-discovery ondersteunen vinden alles zelf via `/.well-known/oauth-protected-resource`; anders registreer je de client eenmalig op `POST /api/oauth/register` met `client_name` en `redirect_uris`.

De autorisatiecode-flow draait op `https://app.cijfr.com/oauth/authorize` met verplichte PKCE (`S256`). Je ziet een toestemmingsscherm met de app-naam, de gevraagde rechten en de omgeving die je koppelt; eigenaren en beheerders kunnen de koppeling desgewenst aan één huisstijlprofiel binden.

## Tokens

- `POST /api/oauth/token` wisselt de code in voor een access token (`cijfr_live_…`, één uur geldig) plus een roterende refresh token (dertig dagen).
- `grant_type=refresh_token` levert een nieuw paar; het oude paar sterft direct.
- `POST /api/oauth/revoke` trekt een grant in. In Cijfr zelf verwijder je de sleutel onder Instellingen → API; dat stopt de app onmiddellijk.

## Tools en grenzen

De tools zijn `me`, `list_*` en `create_*` voor klanten, producten, facturen, abonnementen en betaallinks: dezelfde scopes en regels als de REST-API. Er is bewust geen update- of delete-tool. Wie iets wil verwijderen of wijzigen doet dat in de app, en een verstuurde factuur is ook via MCP onveranderbaar.

- Elke call authenticeert opnieuw: een ingetrokken sleutel of verlopen token werkt meteen niet meer.
- Mutaties accepteren `idempotencyKey` in de arguments; zonder sleutel maakt de server er per call een, zodat retries veilig zijn.
- Scope-fouten komen terug als tool-error met `{error: "forbidden"}`, rate limits als `rate_limited`.