Getypeerde MCP-output: waarom 600+ tools outputSchema hebben

Een MCP-tool kan van alles retourneren - het protocol vereist geen beschrijving van de antwoordvorm. Daarom geven de meeste servers de agent kale JSON, en het model raadt de structuur uit de tekst. Dit werkt totdat het misgaat: de agent pakt een veld dat niet bestaat, of interpreteert de nesteling verkeerd.

Wij hebben de strikte weg gekozen: meer dan 600 van onze MCP-tools publiceren outputSchema - een machinaal schema van het antwoord, gegenereerd uit hetzelfde OpenAPI-contract als de REST API.

Wanneer een tool een uitvoerschema declareert, kent de client de vorm van het antwoord vóór de aanroep. De agent raadt niet - hij ziet dat chart.houses.ascendant bestaat en het type ‘getal, ecliptische lengte in graden’ heeft. Minder hallucinaties over de structuur, een nauwkeurigere aanroepketen, de mogelijkheid om het antwoord aan de clientzijde te valideren.

De catalogus is stapsgewijs gegroeid: 285 tools bij de start, daarna 624, nu meer dan 630 - en de getypeerde uitvoer heeft bijna volledige dekking bereikt (meer dan 600 van de 630+). De schema’s worden niet handmatig geschreven: de generator leest live /v1/openapi.json tijdens de build, dus drift tussen REST en MCP is per constructie onmogelijk.

Strikt zijn heeft een prijs. Wanneer een tool een closed-schema declareert (geen velden buiten de opgesomde), en het antwoord bevat aanvullende metadata, dan wijst een strict-mode client dit af. Bij de chart-family tools hebben we precies dit probleem ondervonden:

McpError: MCP error -32602: Structured content does not match
the tool's output schema: data must NOT have additional properties

De reden: de gegenereerde Zod-schema’s waren in closed-vorm, terwijl het daadwerkelijke antwoord van de backend verschillende service-metadata-velden bevatte die niet in het schema waren gedeclareerd. De client valideerde structuredContent tegen het schema in strict-modus en gaf -32602 terug.

Een interessant detail: Claude Desktop en Cursor toonden de bug niet - zij werken in loose-modus en slaan extra velden over. Het waren juist de strict-mode SDK-clients die crashten, omdat zij strikt valideren. Dit betekent dat het probleem onzichtbaar was in de meest populaire clients en alleen naar voren kwam in eigen integraties bovenop de MCP SDK.

De oplossing is om de typering niet weg te gooien, maar de schema’s open te maken. In de toolgenerator worden de uitvoer ZodObject-schema’s omgezet naar een passthrough-vorm: gedeclareerde velden blijven verplicht en getypeerd, terwijl aanvullende servicevelden de validatie doorstaan zonder de aanroep te laten crashen.

Voor de hosted-catalogus is afzonderlijk een noodoplossing toegepast - het deregistreren van outputSchema voor tools waar de validatie toch al kapot was, zodat strict-clients niet crashen totdat de schema’s volledig open zijn. Een bewuste compromis: beter een correcte aanroep zonder clientvalidatie dan een harde crash.

De les is eenvoudig: getypeerde MCP-uitvoer is nuttig, maar het antwoordschema moet openstaan voor aanvullende velden. API’s evolueren, metadata verschijnt, en een closed-schema verandert elke dergelijke toevoeging in een breaking change voor strict-clients.

De getypeerde catalogus is op twee manieren beschikbaar:

// hosted, без установки
{
  "mcpServers": {
    "astroway": {
      "url": "https://mcp.astroway.info/mcp",
      "headers": { "Authorization": "Bearer aw_live_..." }
    }
  }
}

Of het stdio-pakket npx -y @astroway/mcp met een sleutel in ASTROWAY_API_KEY. Beide leveren dezelfde getypeerde catalogus; een complete gids voor clients vind je op /agent-setup/.