Τυποποιημένη έξοδος MCP: γιατί 600+ εργαλεία έχουν outputSchema

Ένα εργαλείο MCP μπορεί να επιστρέψει οτιδήποτε: το πρωτόκολλο δεν απαιτεί να περιγράφεται η μορφή της απάντησης. Γι’ αυτό οι περισσότεροι servers δίνουν στον agent σκέτο JSON, και το μοντέλο μαντεύει τη δομή από το κείμενο. Αυτό λειτουργεί μέχρι να σπάσει: ο agent παίρνει ένα πεδίο που δεν υπάρχει ή ερμηνεύει λάθος την εμφώλευση.

Εμείς διαλέξαμε τον αυστηρό δρόμο: πάνω από 600 από τα εργαλεία MCP μας δημοσιεύουν outputSchema, ένα schema της απάντησης για μηχανές, παραγμένο από το ίδιο συμβόλαιο OpenAPI με το REST API.

Όταν ένα εργαλείο δηλώνει schema εξόδου, ο client ξέρει τη μορφή της απάντησης πριν από την κλήση. Ο agent δεν μαντεύει: βλέπει ότι το chart.houses.ascendant υπάρχει και έχει τύπο “αριθμός, εκλειπτικό μήκος σε μοίρες”. Λιγότερες παραισθήσεις για τη δομή, ακριβέστερη αλυσίδα κλήσεων, δυνατότητα επικύρωσης της απάντησης στην πλευρά του client.

Ο κατάλογος μεγάλωσε σταδιακά: 285 εργαλεία στην αρχή, μετά 624, τώρα πάνω από 630, και η τυποποιημένη έξοδος έφτασε σχεδόν σε πλήρη κάλυψη (πάνω από 600 από τα 630+). Τα schemas δεν γράφονται με το χέρι: ο generator διαβάζει το live /v1/openapi.json κατά το build, οπότε drift ανάμεσα σε REST και MCP είναι αδύνατο εκ κατασκευής.

Η αυστηρότητα έχει κόστος. Όταν ένα εργαλείο δηλώνει κλειστό schema (κανένα πεδίο πέρα από τα απαριθμημένα) και η απάντηση περιέχει επιπλέον metadata, ένας client σε strict mode την απορρίπτει. Στα εργαλεία της οικογένειας chart πιάσαμε ακριβώς αυτό:

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

Αιτία: τα παραγμένα Zod schemas ήταν σε κλειστή μορφή, ενώ η πραγματική απάντηση του backend περιείχε μερικά βοηθητικά πεδία metadata που δεν είχαν δηλωθεί στο schema. Ο client επικύρωνε το structuredContent έναντι του schema σε strict mode και πετούσε -32602.

Μια ενδιαφέρουσα λεπτομέρεια: το Claude Desktop και το Cursor δεν έδειχναν το bug, γιατί λειτουργούν σε loose mode και αφήνουν να περάσουν τα επιπλέον πεδία. Αποτύγχαναν ακριβώς οι SDK clients σε strict mode, που επικυρώνουν αυστηρά. Δηλαδή το πρόβλημα ήταν αόρατο στους πιο δημοφιλείς clients και εμφανιζόταν μόνο σε δικές σου ενσωματώσεις πάνω στο MCP SDK.

Η λύση δεν ήταν να πεταχτεί η τυποποίηση, αλλά να γίνουν τα schemas ανοιχτά. Στον generator των εργαλείων τα Zod schemas τύπου ZodObject της εξόδου μετατρέπονται σε μορφή passthrough: τα δηλωμένα πεδία μένουν υποχρεωτικά και με τύπους, ενώ τα επιπλέον βοηθητικά πεδία περνούν την επικύρωση χωρίς να ρίχνουν την κλήση.

Για τον hosted κατάλογο εφαρμόστηκε χωριστά και μια εφεδρική λύση: αφαίρεση του outputSchema από την εγγραφή των εργαλείων όπου η επικύρωση ήταν ούτως ή άλλως χαλασμένη, ώστε οι strict clients να μην αποτυγχάνουν μέχρι να ανοίξουν πλήρως τα schemas. Ο συμβιβασμός είναι συνειδητός: καλύτερα μια σωστή κλήση χωρίς επικύρωση στον client παρά μια σκληρή αποτυχία.

Το δίδαγμα είναι απλό: η τυποποιημένη έξοδος MCP είναι χρήσιμη, αλλά το schema της απάντησης πρέπει να είναι ανοιχτό σε επιπλέον πεδία. Το API εξελίσσεται, εμφανίζονται νέα metadata, και ένα κλειστό schema μετατρέπει κάθε τέτοια προσθήκη σε breaking change για τους strict clients.

Ο τυποποιημένος κατάλογος είναι διαθέσιμος και με τους δύο τρόπους:

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

Ή το πακέτο stdio npx -y @astroway/mcp με το key στο ASTROWAY_API_KEY. Και οι δύο δίνουν τον ίδιο τυποποιημένο κατάλογο· ο πλήρης οδηγός ανά client βρίσκεται στο /agent-setup/.