MCP

POST https://ervazo.com/api/mcp met dezelfde bearer-sleutel als de REST-API. De vlag Publieke API moet aan staan. Zie de REST-pagina voor aanmaken, intrekken en de limiet van acht sleutels.

GET /api/mcp heeft geen sleutel nodig en zegt alleen waar je moet posten.

{
  "name": "ervazo",
  "mcp": "POST /api/mcp",
  "protocol": "2025-03-26"
}

Elk POST-bericht is één JSON-RPC-object. jsonrpc is 2.0. id komt ongewijzigd terug, ook als het een string is. Een notificatie zonder id waarvan de method met notifications/ begint, krijgt 202 en een lege body.

De body mag 40.000 bytes zijn. Groter is 413, buiten JSON-RPC om. Ongeldige JSON is foutcode -32700, HTTP 400.

Methoden die deze server kent: initialize, ping, tools/list, tools/call. Iets anders is -32601, Method not found. Een andere HTTP-methode dan GET of POST is 405.

Een client die een externe HTTP-server ondersteunt, wijst naar het POST-adres en stuurt de sleutel mee. Vervang de sleutel. Zet hem niet in een gedeelde repo.

{
  "mcpServers": {
    "ervazo": {
      "url": "https://ervazo.com/api/mcp",
      "headers": {
        "Authorization": "Bearer nal_jouw_sleutel"
      }
    }
  }
}

De client hoort eerst initialize te sturen, daarna tools/list, en per actie tools/call. Ervazo duwt geen lijstwijziging: capabilities.tools.listChanged is false.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": { "name": "voorbeeld", "version": "1.0.0" }
  }
}

params worden niet gecontroleerd. Het antwoord noemt het protocol en de server.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": { "tools": { "listChanged": false } },
    "serverInfo": { "name": "ervazo", "version": "1.0.0" }
  }
}

Leeg resultaat. Handig om de sleutel en de vlag te testen zonder een dossier aan te raken.

{ "jsonrpc": "2.0", "id": 2, "method": "ping" }

{ "jsonrpc": "2.0", "id": 2, "result": {} }

De zes hulpmiddelen, met JSON-Schema. additionalProperties is false. Een extra veld in arguments wordt bij de call genegeerd doordat alleen de bekende velden worden gelezen, maar een strikte client hoort ze niet te sturen.

{ "jsonrpc": "2.0", "id": 3, "method": "tools/list" }

name is de hulpmiddelnaam. arguments is een object. Het resultaat staat niet als losse JSON-RPC-data, maar als tekst in content. Die tekst is zelf JSON. isError is true als het dossier ontbreekt of de invoer wordt geweigerd.

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "list_dossiers",
    "arguments": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      { "type": "text", "text": "{\"dossiers\":[]}" }
    ],
    "isError": false
  }
}

Parseer text dus nog een keer. Een onbekende naam geeft in die tekst {"error":"Onbekend hulpmiddel."} en isError true.

list_dossiers

Geen argumenten. Zelfde lijst als GET /api/v1/dossiers: id, reference, line, phase, status, name, death. Geen documenten en geen BSN.

get_dossier

Verplicht: dossierId. Antwoord onder dossier: id, reference, line, phase, status, firstName, lastName, birth, death, residence. Geen privénotities.

{ "name": "get_dossier", "arguments": { "dossierId": "…" } }

list_parties

Verplicht: dossierId. Elke betrokkene heeft id, type, name, email, relation en portal. De privénotitie van de persoon gaat niet mee.

list_tasks

Verplicht: dossierId. Elke taak heeft id, title, due en status.

add_task

Verplicht: dossierId en title. due is optioneel, formaat YYYY-MM-DD. Zonder geldige datum wordt het vandaag. title wordt getrimd tot 200 tekens. Een lege titel is een fout. Op een gesloten dossier ook. De taak staat open en komt in het auditlog als api.task.

{
  "name": "add_task",
  "arguments": {
    "dossierId": "…",
    "title": "Polis opvragen",
    "due": "2026-11-12"
  }
}

add_note

Verplicht: dossierId en body. Hoogstens 4000 tekens na trim. De notitie is internal, auteur API, en verschijnt niet in het erfgenamenportaal. Het auditlog krijgt api.note.

{
  "name": "add_note",
  "arguments": {
    "dossierId": "…",
    "body": "Verzekeraar gevraagd om de polis."
  }
}

• 401 — Dezelfde sleutelfout als de REST-API, vóór JSON-RPC.
• 403 — API uit, of account gepauzeerd.
• 429 — Meer dan 120 verzoeken per minuut voor deze sleutel. REST en MCP tellen samen.
• 413 — Body groter dan 40.000 bytes.
• 400 en -32700 — De body is geen JSON.
• -32601 — Onbekende method.
• Dossier niet gevonden — HTTP 200, isError true, text is de zin Dossier niet gevonden.
• Lege titel, lege notitie of gesloten dossier — HTTP 200, isError true, text is JSON met error.

Een ontbrekend dossier is dus geen HTTP 404 bij MCP. Alleen de tekst en isError zeggen het.

Eén sleutel, één account. Geen bestanden, geen BSN, geen verwijderen, geen uitnodiging en geen verdeling. Schrijven op een gesloten dossier stopt. De REST-pagina beschrijft de velden die in de tekst-JSON terugkomen.

Terug naar de REST-API