Ieșire MCP tipizată: de ce 600+ instrumente au outputSchema

MCP-instrumentul poate returna orice - protocolul nu cere sa se descrie forma raspandirii. Astfel, majoritatea serverelor returneaza agentului un JSON gol, iar modelul isi imagineaza structura din text. Acest lucru functioneaza, pana cand nu mai functioneaza: agentul isi ia un camp, care nu exista, sau il interpreteaza in mod incorect.

Ne-am hotarat sa mergem pe cale strasa: peste 600 dintre MCP-instrumentele noastre publiceaza outputSchema - o schema maquina, generata din acelasi OpenAPI-contract, care si el este folosit de REST API.

Cand instrumentul anunta schema de iesire, clientul stie forma raspandirii pentru apelul respectiv. Agentul nu isi imagineaza schema - el vede ca chart.houses.ascendant exista si are tipul “numar, latitudine ecuatoriala in grade”. Mai putine galucinatii despre structura, mai corecti apeluri, posibilitatea de a valida raspunsul pe partea clientului.

Catalogul a crescut gradual: 285 instrumente la inceput, apoi 624, si acum peste 630 - si schema de iesire a fost tipizata aproape complet (peste 600 din 630+). Schemele nu sunt scrise manual: generatorul citeste live /v1/openapi.json pe server, astfel ca driftul intre REST si MCP este imposibil de realizat dupa construire.

Strasitatea are pret. Cand instrumentul anunta o schema inchisa (nici un camp mai mult decat cel declarat), si raspunsul contine metadate suplimentare, clientul strict refuza asta. Pe instrumentele chart-family, am prins exact asta:

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

Caiza: schemele Zod generatoare aveau forma inchisa, iar raspunsul real al serverului contina mai multe metadate servicii, care nu erau declarate in schema. Clientul a validat structuredContent impotriva schemei in mod strict si a aruncat -32602.

Interesant: Claude Desktop si Cursor bug nu au aparat - ele functionau in mod loose si au ignorat metadatele suplimentare. Clientii stricti, care valideaza strict, au fost cei care au avut problema. Adica problema nu a aparat in cele mai populare clienti si a aparat doar in integrarile noastre proprii pe partea de MCP SDK.

Solutia - nu a fi lipsit de tipizare, dar sa facem schemele deschise. In generatorul instrumentelor, schemele ZodObject de iesire sunt transformate in forma passthrough: campurile declarate raman obligatorii si tipizate, iar metadatele servicii suplimentare sunt validate, fara a fi valdate apelul.

Pentru catalogul gazduit separat, am aplicat o varianta de rezervare - sa nu se mai declare outputSchema pentru instrumentele, unde validarea a fost deja sparta, astfel ca clientii stricti sa nu mai aiba problema, pana cand schemele nu sunt deschise complet. Compromisul este recunoscut: mai bine un apel corect fara validare client, decat un blocaj strict.

Lectioneaza simpla: tipizarea de iesire a MCP este utila, dar schema raspandirii trebuie sa fie deschisa pentru metadate suplimentare. API-ul evolueaza, metadatele apar, si schema inchisa transforma fiecare astfel de adaugare in schimbare de breaking pentru clientii stricti.

Catalogul tipizat este disponibil in doua moduri:

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

Sau pacetul stdio npx -y @astroway/mcp cu cheia API in ASTROWAY_API_KEY. Ambele returneaza acelasi catalog tipizat; ghidul complet pentru clienti - pe /agent-setup/.