Protocol en foutcodes

Deze pagina is voor wie zelf een MCP-client bouwt of wil weten wat er onder de motorkap gebeurt. Gebruik je Claude Code of Cursor, dan regelt de tool dit voor je en heb je genoeg aan Koppelen in je AI-tool.

Transport

• MCP over HTTP, alleen met vraag en antwoord. Elk verzoek is één POST met een JSON-RPC 2.0-bericht of een batch van berichten.
• Het antwoord is application/json. De server stuurt geen stream en gebruikt geen sessie-id.
• Elke andere methode dan POST geeft 405 met de header Allow: POST en een lege body.
• Elk verzoek, ook initialize, heeft de header Authorization: Bearer met je sleutel nodig.

curl -X POST https://api.leadforge.nl/client-mcp \
  -H "Authorization: Bearer JOUW_SLEUTEL" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Methodes

De servers hebben geen resources en geen prompts. Elke andere methode met een id, zoals resources/list, geeft de fout -32601 met de melding method niet ondersteund en de naam van de methode. Een bericht zonder id is een notificatie en krijgt geen antwoord.

Protocolversie

De standaardversie is 2025-06-18. Stuurt de client bij initialize een protocolVersion mee, dan stuurt de server die versie letterlijk terug.

Voorbeelden

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "studio-noord-klanten", "version": "1.0.0" }
  }
}

De naam in serverInfo is bij een sleutel van een bureau de servernaam uit de configuratie, zoals studio-noord-klanten.

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

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

{"jsonrpc":"2.0","method":"notifications/initialized"}

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"klant_prestaties","arguments":{"klant":"Klant A","weken":4}}}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "..." }],
    "isError": false
  }
}

Batch

Je mag een array van berichten sturen, hoogstens 50. Bij meer geeft de server 400 met -32600 en te veel berichten in een batch. De antwoorden komen terug als array, zonder antwoorden op notificaties. Levert geen enkel bericht een antwoord op, ook bij een lege array, dan is het antwoord 202 zonder body.

[
  {"jsonrpc":"2.0","method":"notifications/initialized"},
  {"jsonrpc":"2.0","id":3,"method":"ping"},
  {"jsonrpc":"2.0","id":4,"method":"resources/list"}
]

[
  {"jsonrpc":"2.0","id":3,"result":{}},
  {"jsonrpc":"2.0","id":4,"error":{"code":-32601,"message":"method niet ondersteund: resources/list"}}
]

Volgorde van controles

De server controleert elk verzoek in deze volgorde, en stopt bij de eerste fout:

1. De sleutel: ontbreekt of klopt hij niet, dan 401.
2. De limiet: boven 120 per minuut, dan 429.
3. Het bereik: een sleutel met een selectie klanten op Websites of Kennisbank, dan 403.
4. De body: geen geldige JSON, of geen object of array, dan 400.
5. Het JSON-RPC-bericht zelf.

Limiet

• Hoogstens 120 verzoeken per sleutel per minuut. Elke sleutel heeft zijn eigen teller.
• Eén HTTP-verzoek telt als één, ook een batch.
• Het is een vast venster van 60 seconden dat begint bij het eerste verzoek. Rond de grens van twee vensters kunnen er kort meer door.
• Boven de limiet antwoordt de server met 429, de header Retry-After met de seconden tot het venster afloopt (minstens 1) en de fout -32003. Een geweigerd verzoek telt ook mee.
• Een verzoek met een onbekende of ingetrokken sleutel telt niet.

HTTP/1.1 429 Too Many Requests
Retry-After: 40
Content-Type: application/json

{"jsonrpc":"2.0","id":null,"error":{"code":-32003,"message":"te veel aanroepen: hooguit 120 per minuut per sleutel, probeer het over 40 s opnieuw"}}

Foutcodes

Bij deze fouten is het id in het antwoord altijd null, behalve bij -32601.

{"jsonrpc":"2.0","id":null,"error":{"code":-32001,"message":"auth vereist"}}

Fouten in een tool

Een fout binnen een tool komt terug als gewoon resultaat van tools/call. Alleen in twee gevallen staat isError op true:

• een tool die niet bestaat: fout: onbekende tool met de naam;
• een storing bij het ophalen: fout: de tool kon dit niet ophalen. Details van de storing gaan niet mee.

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [{ "type": "text", "text": "fout: onbekende tool: cro_verzonnen" }],
    "isError": true
  }
}

Verder lezen

• Problemen oplossen
• Beveiliging