Output tipizzato MCP: perché 600+ strumenti hanno outputSchema

L’MCP-tool può restituire qualsiasi cosa - il protocollo non richiede di descrivere la forma della risposta. Pertanto, la maggior parte dei server restituisce all’agente un JSON grezzo, e il modello indovina la struttura dal testo. Funziona finché non si rompe: l’agente prende un campo che non esiste o interpreta male l’annidamento.

Abbiamo seguito una strada rigorosa: oltre 600 dei nostri MCP-tools pubblicano outputSchema - uno schema macchina della risposta, generato dallo stesso contratto OpenAPI del REST API.

Quando uno strumento dichiara uno schema di output, il cliente conosce la forma della risposta prima della chiamata. L’agente non deve indovinare - vede che chart.houses.ascendant esiste ed è di tipo “numero, longitudine eclittica in gradi”. Meno allucinazioni sulla struttura, una catena di chiamate più precisa, la possibilità di validare la risposta lato cliente.

Il catalogo è cresciuto gradualmente: 285 strumenti all’inizio, poi 624, ora oltre 630 - e l’output tipizzato ha quasi raggiunto una copertura completa (oltre 600 su 630+). Gli schemi non vengono scritti a mano: il generatore legge il live /v1/openapi.json durante il build, quindi uno drift tra REST e MCP è impossibile per costruzione.

La rigidità ha un prezzo. Quando uno strumento dichiara uno schema chiuso (nessun campo oltre quelli elencati) e la risposta contiene metadati aggiuntivi, il cliente in modalità strict lo rifiuta. Sugli strumenti della famiglia chart abbiamo esattamente questo:

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

Motivo: gli schemi Zod generati erano in forma chiusa, mentre la risposta effettiva del backend portava alcuni campi di metadati di servizio, non dichiarati nello schema. Il cliente validava structuredContent contro lo schema in modalità strict e lanciava -32602.

Un interessante dettaglio: Claude Desktop e Cursor non mostravano il bug - sono in modalità loose e ignorano i campi aggiuntivi. Andavano in crash solo i client SDK in modalità strict, che validano rigidamente. Quindi il problema era invisibile nei client più popolari e emergeva solo nelle integrazioni personalizzate basate su MCP SDK.

La soluzione non è eliminare la tipizzazione, ma rendere gli schemi aperti. Nel generatore di strumenti, gli schemi ZodObject di output vengono convertiti in forma passthrough: i campi dichiarati rimangono obbligatori e tipizzati, mentre i campi di servizio aggiuntivi passano la validazione senza bloccare la chiamata.

Per il catalogo hosted è stato applicato un workaround separato: rimuovere outputSchema dalla registrazione di quegli strumenti dove la validazione era già rotta, in modo che i client strict non cadano mentre gli schemi non sono completamente aperti. Un compromesso consapevole: meglio una chiamata corretta senza validazione client che un crash rigido.

La lezione è semplice: l’output tipizzato di MCP è utile, ma lo schema di risposta deve essere aperto ai campi aggiuntivi. Le API evolvono, i metadati appaiono, e uno schema chiuso trasforma ogni tale aggiunta in un breaking change per i client strict.

Il catalogo tipizzato è disponibile in entrambi i modi:

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

Oppure il pacchetto stdio npx -y @astroway/mcp con la chiave in ASTROWAY_API_KEY. Entrambi restituiscono lo stesso catalogo tipizzato; la guida completa per i client è su /agent-setup/.