Sortie MCP typée : pourquoi 600+ outils ont un outputSchema

MCP-інструмент може повернути що завгодно - протокол не вимагає описувати форму відповіді. Тому більшість серверів віддають агенту голий JSON, а модель вгадує структуру з тексту. Це працює, поки не ламається: агент бере поле, якого немає, або неправильно інтерпретує вкладеність.

Ми пішли строгим шляхом: понад 600 з наших MCP-інструментів публікують outputSchema - машинну схему відповіді, згенеровану з того самого OpenAPI-контракту, що й REST API.

Lorsque l’outil déclare le schéma de sortie, le client connaît la forme de la réponse avant l’appel. L’agent ne devine plus - il voit que chart.houses.ascendant existe et a le type «nombre, longitude écliptique en degrés». Moins d’hallucinations sur la structure, une chaîne d’appels plus précise, la possibilité de valider la réponse côté client.

Le catalogue a grandi par étapes : 285 outils au départ, puis 624, maintenant plus de 630 - et la sortie typée a presque atteint une couverture complète (plus de 600 sur 630+). Les schémas ne sont pas écrits à la main : le générateur lit en direct /v1/openapi.json sur le build, donc le drift entre REST et MCP est impossible par construction.

La rigueur a un prix. Quand un outil déclare un schéma closed (aucun champ au‑delà de ceux listés), et que la réponse contient des métadonnées supplémentaires, le client en mode strict le rejette. Sur les outils chart-family nous avons attrapé exactement cela :

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

Cause : les schémas Zod générés étaient en forme closed, et la réponse réelle du backend contenait plusieurs champs de métadonnées de service, non déclarés dans le schéma. Le client validait structuredContent contre le schéma en mode strict et renvoyait -32602.

Un détail intéressant : Claude Desktop et Cursor n’affichaient pas le bug - ils sont en mode loose et laissent passer les champs supplémentaires. Ce sont les clients SDK en mode strict qui tombaient, ceux qui valident strictement. Donc le problème était invisible dans les clients les plus populaires et ne surgissait que dans les intégrations propres au‑dessus du SDK MCP.

La solution - ne pas abandonner la typage, mais rendre les schémas ouverts. Dans le générateur d’outils, les schémas ZodObject de sortie sont convertis en forme passthrough : les champs déclarés restent obligatoires et typés, tandis que les champs de service supplémentaires passent la validation, sans casser l’appel.

Pour le catalogue hébergé, une solution de secours a été appliquée séparément - retirer outputSchema de l’enregistrement de ces outils où la validation était déjà cassée, afin que les clients strict ne tombent pas tant que les schémas ne sont pas entièrement ouverts. Le compromis est conscient : mieux un appel correct sans validation côté client que une défaillance stricte.

Leçon simple : la sortie typée MCP est utile, mais le schéma de réponse doit être ouvert aux champs supplémentaires. L’API évolue, les métadonnées apparaissent, et un schéma closed transforme chaque ajout en breaking change pour les clients strict.

Le catalogue typé est disponible via les deux voies :

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

Ou le paquet stdio npx -y @astroway/mcp avec la clé dans ASTROWAY_API_KEY. Les deux renvoient le même catalogue typé ; le guide complet sur les clients - sur /agent-setup/.