De MCP-tool heeft zijn schema gewijzigd. Je agent heeft het niet gemerkt.

Je tool-aanroep crashte niet. Het gaf een 200-statuscode en geldige JSON terug.

Maar het werd uitgevoerd tegen het verkeerde contract. De upstream-server heeft drie dagen geleden een veld hernoemd. Je agent bleef de oude naam sturen. De server negeerde dit stilletjes. Het resultaat kwam leeg terug. Er verscheen geen foutmelding. Niemand merkte het een week lang op.

Dit is de stille fout (silent failure). Het is niet het luidruchtige soort waarbij logs rood kleuren. Het is het soort waarbij de server vriendelijk terugglimlacht, maar de data onjuist is.

MCP-servers kunnen een tool-contract wijzigen tussen aanroepen door. Ze kunnen een parameter hernoemen of een veldbeschrijving aanpassen. Deze wijzigingen blijven vaak structureel geldig. De JSON-validatie slaagt. De server antwoordt met 200. Je agent handelt op basis van verkeerde data zonder een enkele foutmelding.

De oplossing is eenvoudig: • Leg een SHA-256-hash van elk tool-contract vast (pin). • Neem zowel het schema als de beschrijving op in die hash. • Controleer de hash voor elke aanroep. • Stop de aanroep als het contract afwijkt.

We focussen op de vraag of een tool antwoordt. We controleren statuscodes. We stellen timeouts in. We proberen het opnieuw bij 5xx-fouten. Bijna niemand controleert of het contract is gewijzigd tussen het moment dat de agent het schema leerde en het moment dat hij de aanroep deed.

Een MCP-server stelt tools beschikbaar via tools/list. Elke tool heeft een inputSchema en een beschrijving. Je agent leest dit één keer aan het begin van een sessie.

Als de server wordt bijgewerkt, kan deze:

  • Een parameter hernoemen (zoals query naar q) terwijl extra eigenschappen open blijven staan. De oude parameter wordt stilletjes genegeerd.
  • De betekenis van een veld wijzigen. Een limiet kan veranderen van "max results" naar "page index". Het type blijft een integer, dus de validatie slaagt.
  • Een enum beperken. Een geldige waarde kan worden omgezet naar een nieuwe standaardwaarde.

De MCP-specificatie zegt dat een server een client ZOU MOETEN (SHOULD) informeren als een lijst verandert. Er staat niet dat dit MOET (MUST). Veel servers sturen deze melding niet. Zelfs als ze dat wel doen, vertellen ze je misschien niet dat het schema van een specifieke tool is gewijzigd.

Stop met het vertrouwen op structurele validatie. Het kan een verandering in betekenis niet waarnemen.

Behandel je MCP-tools als software-afhankelijkheden. Gebruik een lockfile-aanpak. Maak bij het eerste contact een SHA-256-hash van het schema en de beschrijving van de tool. Bereken de hash opnieuw voor elke aanroep. Als ze overeenkomen, ga dan door. Als ze niet overeenkomen, markeer de afwijking en stop.

Het hashen van de beschrijving is het geheim. Als een parameter verandert van "max results" naar "page index", ziet het schema er hetzelfde uit. De hash verandert echter omdat de woorden zijn veranderd. Dit vangt de semantische afwijking op die validatie mist.

Ga niet gokken wanneer een contract afwijkt. Probeer het niet blindelings opnieuw. Pauzeer, log het verschil en herstel het contract.

Source: https://dev.to/0012303/the-mcp-tool-your-agent-calls-changed-its-schema-it-didnt-notice-5g6m

Optional learning community: https://t.me/GyaanSetuAi