MCP-server

Token maken

Open in de app Instellingen, Koppelingen, en ga naar AI-assistenten koppelen. Geef het token een naam, kies de administratie en hoe lang het geldig is: 30 dagen, 90 dagen, een jaar of zonder einddatum. Zet het vinkje bij Mag ook klanten, uren, conceptfacturen en bonnen toevoegen alleen aan als de assistent dat echt moet kunnen.

Kopieer het token meteen. Goldmary slaat alleen een hash van het token op en kan het je daarna niet meer laten zien. Een week voor de einddatum krijg je een mail.

Claude Code

Zet je token in dit commando en voer het uit in een terminal.

claude mcp add --transport http goldmary https://goldmary.eu/mcp --header "Authorization: Bearer gm_JOUW_TOKEN"

Met claude mcp list zie je of de koppeling werkt. Vraag daarna bijvoorbeeld welke facturen nog openstaan.

Cursor en andere clients

Een client die een server met een eigen header kan toevoegen, werkt met hetzelfde adres en token. In Cursor zet je dit in .cursor/mcp.json.

{
  "mcpServers": {
    "goldmary": {
      "url": "https://goldmary.eu/mcp",
      "headers": {
        "Authorization": "Bearer gm_JOUW_TOKEN"
      }
    }
  }
}

In de Cursor-CLI zet je de server daarna aan met cursor-agent mcp enable goldmary. Met cursor-agent mcp list-tools goldmary zie je welke tools hij heeft.

Claude en ChatGPT in de browser

De connectors van claude.ai en ChatGPT koppelen zonder token. Je logt in bij Goldmary en geeft daar toestemming.

1. Voeg in de assistent een eigen connector toe met het adres https://goldmary.eu/mcp.
2. Vraagt de assistent om een client-ID, vul dan claude in bij Claude en chatgpt bij ChatGPT. Een client-geheim is er niet, dat veld blijft leeg.
3. De assistent stuurt je naar Goldmary. Ben je niet ingelogd, dan log je eerst in.
4. Kies de administratie en hoe lang de koppeling geldig is. Zet het vinkje bij Mag ook klanten, uren, conceptfacturen en bonnen toevoegen alleen aan als de assistent dat moet kunnen.
5. Klik op Toestaan. Je gaat terug naar de assistent. Klik je op Weigeren, dan krijgt de assistent geen toegang.

De koppeling staat daarna in de app bij Instellingen, Koppelingen, onder AI-assistenten koppelen, als Claude via OAuth of ChatGPT via OAuth. Het toegangstoken is een uur geldig. Daarna kan de assistent met een verversingssleutel een nieuw token halen, tot de einddatum die je koos. Met Intrekken stopt de koppeling bij de volgende vraag van de assistent. Log je uit, dan stopt elke koppeling via OAuth ook en koppel je opnieuw. Een token dat je zelf maakte, blijft dan werken.

Een andere assistent kan zich aanmelden met als client-ID het adres van zijn eigen Client ID Metadata Document. Het toestemmingsscherm toont dan zijn naam en zijn domein. Ken je dat domein niet, klik dan op Weigeren.

Wat de assistent kan

Met elk token leest de assistent facturen, klanten, uren, bonnen, boekingen, de btw per periode, de winst-en-verliesrekening en de balans.

• list_invoices
• get_invoice
• list_customers
• adres_opzoeken
• get_customer
• list_hours
• list_expenses
• get_expense
• list_bookings
• get_booking
• vat_period
• profit_and_loss
• balance_sheet

Met een token dat ook mag schrijven, voegt de assistent klanten en bonnen toe, zet hij uren op een project en maakt hij conceptfacturen.

• create_customer
• set_hours
• create_invoice
• create_expense

Een conceptfactuur krijgt geen nummer en gaat nergens heen, en een bon van de assistent is nog niet geboekt. Versturen, definitief maken, boeken of verwijderen doe je zelf in de app.

Sandbox

Proberen zonder je eigen boekhouding kan met een sandbox. Klik in de app bij Instellingen, Koppelingen, onder AI-assistenten koppelen op Sandbox maken. Je krijgt een eigen administratie met verzonnen cijfers. Maak daarna een token voor die administratie. Uit een sandbox gaat niets naar buiten. Mail, Peppol, betalingen en leden staan er uit.

REST API

Hetzelfde token werkt ook als sleutel voor de REST API, op de routes van zijn eigen administratie. Een token dat alleen mag lezen, leest; een token dat ook mag schrijven, voegt daarnaast klanten en bonnen toe, zet uren en maakt conceptfacturen, net als de assistent. De routes staan in openapi.json (OpenAPI 3.1).

curl https://goldmary.eu/api/v1/administraties/JOUW_ADMINISTRATIE_ID/invoices -H "Authorization: Bearer gm_JOUW_TOKEN"

Vernieuwen, intrekken en grenzen

Trek je een token in, dan werkt het vanaf de volgende vraag van de assistent niet meer. Een verlopen token werkt ook niet meer. Vernieuw je een token, dan krijg je een nieuw token met dezelfde naam, rechten en einddatum en werkt het oude meteen niet meer. Goldmary legt elke vraag vast, met de tool en of het lukte. In de app zie je bij elk token onder Gebruik de vragen van de afgelopen 90 dagen, met tijd en plaats.

Per token zijn 60 vragen per minuut mogelijk, en per internetadres 300. Wie daarboven zit, krijgt even geen antwoord.

Webhooks

Een eigenaar of beheerder zet in de app bij Instellingen, Koppelingen, onder Webhooks een https-adres. Goldmary stuurt daar een POST met JSON heen als een factuur definitief wordt (invoice.finalized), als een factuur betaald is (invoice.paid) en als er een klant bij komt (customer.created). Een administratie heeft hoogstens vijf adressen.

{
  "id": "…",
  "event": "invoice.paid",
  "created": "2026-10-01T09:00:00.000Z",
  "administratieId": "…",
  "data": {
    "id": "…",
    "number": "2026-0001"
  }
}

Het bericht noemt alleen wat er gebeurde en het id. De rest lees je met een token via de REST API. Het id van het bericht staat ook in de header goldmary-delivery: komt hetzelfde id twee keer binnen, dan is het hetzelfde bericht.

Bij het toevoegen krijg je één keer een geheim. Elk bericht draagt de header goldmary-signature: t=…,v1=…. Reken met het geheim de HMAC-SHA256 uit over de tijd t, een punt en de ruwe body, in hex, en vergelijk die met v1. Wijs een bericht af als t meer dan vijf minuten afwijkt. In Node.js:

const { createHmac, timingSafeEqual } = require("node:crypto");

// kop: de header goldmary-signature, body: de ruwe body als tekst
function echt(kop, body, geheim) {
  const { t, v1 = "" } = Object.fromEntries(kop.split(",").map((d) => d.split("=")));
  const verwacht = createHmac("sha256", geheim).update(`${t}.${body}`).digest("hex");
  return v1.length === 64 && timingSafeEqual(Buffer.from(v1), Buffer.from(verwacht)) && Math.abs(Date.now() / 1000 - Number(t)) < 300;
}

Antwoord binnen 10 seconden met een status 200 tot 299. Anders probeert Goldmary het opnieuw na ongeveer 1, 2, 4, 8 en 16 uur, en na zes pogingen stopt het. Een doorverwijzing volgt Goldmary niet. In de app zie je 30 dagen lang wat er met elk bericht gebeurde.