Met de Peil MCP-server koppel je Peil aan je AI-assistent. MCP is een open standaard — Claude, ChatGPT (OpenAI) en Gemini kunnen er allemaal mee overweg. Daarna kun je je assistent berichten sturen om acties uit te voeren op je Peil account:
- "Log 3 uur voor Bright Agency vandaag: API-koppeling gebouwd."
- "Maak een conceptfactuur voor De Correspondent over juni."
- "Hoeveel staat er open, en wat heb ik dit jaar gefactureerd?"
Concept-eerst, per ontwerp
De assistent werkt met een API-sleutel met eigen rechten. Facturen
maken en versturen zijn bewust gescheiden rechten: zonder Facturen versturen
(invoices:send) kan een assistent alleen concepten maken. In dat geval gaat
nooit iets naar je klanten zonder dat jij het in Peil beoordeelt. Elke bewerking wordt
vastgelegd in de gebruikgeschiedenis van de sleutel.
Stap 1 — maak een API-sleutel
Ga in de Peil-app naar Instellingen → Developer settings (Pro) en maak een sleutel aan met de rechten Lezen, Uren loggen en Facturen beheren. Wil je dat de assistent ook klanten beheert of e-mail verstuurt, voeg dan Klanten beheren respectievelijk Facturen versturen toe. Versturen is een apart recht want het is uiteraard klantgericht en onomkeerbaar. Kies een korte looptijd (bijv. 90 dagen), verlengen is één klik. De sleutel wordt eenmalig getoond; kopieer hem direct.
Stap 2 — voeg de server toe aan je assistent
De MCP-server draait lokaal en praat uitsluitend met de Peil API. Met
uv of
pipx heb je niets te
installeren of te klonen — uvx peil-mcp draait de nieuwste versie op aanvraag
(Python 3.11+). Alle gereedschappen, rechten en configuratie-opties staan op de
peil-mcp‑pagina op PyPI.
De server is voor elke assistent hetzelfde: het commando uvx peil-mcp met je
sleutel als omgevingsvariabele PEIL_API_KEY. Alleen wáár je dat instelt verschilt
per assistent.
Claude Desktop — voeg dit toe aan claude_desktop_config.json:
{
"mcpServers": {
"peil": {
"command": "uvx",
"args": ["peil-mcp"],
"env": { "PEIL_API_KEY": "jouw-sleutel" }
}
}
}Claude Code — één commando:
claude mcp add peil -e PEIL_API_KEY=jouw-sleutel -- uvx peil-mcp Gemini CLI — zet hetzelfde mcpServers-blok als hierboven in
~/.gemini/settings.json (of .gemini/settings.json in je project).
ChatGPT / OpenAI (Codex CLI) — één commando:
codex mcp add peil --env PEIL_API_KEY=jouw-sleutel -- uvx peil-mcp
Of handmatig in ~/.codex/config.toml onder de sectie
[mcp_servers.peil] (let op: mcp_servers met een underscore, TOML).
Andere clients (Cursor, Windsurf, Cline, VS Code …) gebruiken hetzelfde
commando en dezelfde PEIL_API_KEY; alleen het configuratiebestand verschilt. Kan
een client een lokaal MCP-commando starten, dan werkt Peil.
Stap 3 — vraag het gewoon
De assistent kan je hele facturatielus bedienen — afhankelijk van de rechten op de sleutel:
klanten opvragen én beheren (aanmaken, bewerken, verwijderen), uren loggen, bewerken en
verwijderen, ongefactureerde uren bekijken, conceptfacturen maken, de status wijzigen
(bijv. op betaald zetten), facturen verwijderen of archiveren, en herinneringsteksten
schrijven. Alles wat een e-mail naar je klant stuurt — een factuur versturen, een verzending
inplannen of een herinnering mailen — zit achter het aparte recht invoices:send
en vraagt eerst je bevestiging. Klantnamen hoef je niet exact te typen — "Bright" vindt
Bright Agency, en bij twijfel vraagt de assistent welke klant je bedoelt.
Goed om te weten
- Intrekken is direct. Trek de sleutel in via Developer settings en de assistent verliest per direct alle toegang.
- Het logboek is je zicht. Elke actie van de sleutel (uren, concepten, verzendingen) staat in het activiteitenlogboek bij de sleutel.
- Limieten. Schrijfacties zijn gelimiteerd (uren 60/min, concepten 20/min, verzenden 10/min) — ruim voldoende voor normaal gebruik, krap genoeg om ongelukken te dempen.
Liever zelf bouwen zonder MCP? De volledige REST-referentie staat in de API referentie.