Output MCP tipizat: de ce peste 600 de instrumente au outputSchema

Un instrument MCP poate returna orice: protocolul nu cere descrierea formei răspunsului. De aceea majoritatea serverelor îi dau agentului JSON gol, iar modelul ghicește structura din text. Merge până nu mai merge: agentul ia un câmp care nu există sau interpretează greșit imbricarea.

Noi am ales calea strictă: peste 600 dintre instrumentele noastre MCP publică outputSchema, o schemă a răspunsului citibilă de mașini, generată din același contract OpenAPI ca și REST API-ul.

Când un instrument își declară schema de ieșire, clientul cunoaște forma răspunsului înainte de apel. Agentul nu ghicește: vede că chart.houses.ascendant există și are tipul “număr, longitudine ecliptică în grade”. Mai puține halucinații despre structură, un lanț de apeluri mai precis și posibilitatea de a valida răspunsul pe partea clientului.

Catalogul a crescut în etape: 285 de instrumente la lansare, apoi 624, acum peste 630, iar output-ul tipizat a ajuns aproape la acoperire completă (peste 600 din 630+). Schemele nu se scriu de mână: generatorul citește /v1/openapi.json live la build, așa că un drift între REST și MCP este imposibil prin construcție.

Strictețea are un preț. Când un instrument declară o schemă closed (niciun câmp în afara celor enumerate), iar răspunsul conține metadate suplimentare, un client strict-mode îl respinge. Pe instrumentele din familia chart am prins exact asta:

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

Cauza: schemele Zod generate erau în formă closed, iar răspunsul real al backend-ului conținea câteva câmpuri de metadate de serviciu, nedeclarate în schemă. Clientul valida structuredContent față de schemă în modul strict și arunca -32602.

Un detaliu interesant: Claude Desktop și Cursor nu arătau bug-ul, pentru că rulează în mod loose și lasă să treacă câmpurile suplimentare. Cădeau tocmai clienții SDK strict-mode, care validează riguros. Cu alte cuvinte, problema era invizibilă în cei mai populari clienți și ieșea la suprafață doar în integrările proprii construite peste MCP SDK.

Soluția nu a fost să renunțăm la tipizare, ci să facem schemele deschise. În generatorul de instrumente, schemele ZodObject de ieșire sunt trecute în formă passthrough: câmpurile declarate rămân obligatorii și tipizate, iar câmpurile de serviciu suplimentare trec validarea fără să pice apelul.

Pentru catalogul hosted s-a aplicat separat o variantă de rezervă: eliminarea outputSchema din înregistrarea instrumentelor la care validarea era oricum stricată, ca să nu cadă clienții stricți până când schemele sunt complet deschise. Un compromis asumat: mai bine un apel corect fără validare pe client decât o eroare fatală.

Lecția e simplă: output-ul MCP tipizat este util, dar schema răspunsului trebuie să fie deschisă pentru câmpuri suplimentare. API-ul evoluează, apar metadate noi, iar o schemă closed transformă fiecare astfel de adăugare într-o breaking change pentru clienții stricți.

Catalogul tipizat este disponibil pe ambele căi:

// hosted, nothing to install
{
  "mcpServers": {
    "astroway": {
      "url": "https://mcp.astroway.info/mcp",
      "headers": { "Authorization": "Bearer aw_live_..." }
    }
  }
}

Sau pachetul stdio npx -y @astroway/mcp, cu cheia în ASTROWAY_API_KEY. Ambele oferă același catalog tipizat; ghidul complet pentru fiecare client este la /agent-setup/.