Tipizált MCP kimenet: miért 600+ eszköznek van outputSchema

MCP‑eszköz bármit visszaadhat – a protokoll nem követeli meg a válasz formájának leírását. Ezért a legtöbb szerver a ügynöknek nyers JSON‑t ad, és a modell a szövegből találja ki a struktúrát. Ez működik, amíg nem romlik: az ügynök olyan mezőt vesz, ami nincs, vagy helytelenül értelmezi a beágyazottságot.

Szigorú útra léptünk: több mint 600 MCP‑eszközünk közzéteszi az outputSchema‑t – a válasz gépi sémáját, amely ugyanabból az OpenAPI‑szerződésből lett generálva, mint a REST API.

Amikor egy eszköz bejelenti a kimeneti sémát, a kliens már a hívás előtt ismeri a válasz formáját. Az ügynök nem találgat – látja, hogy a chart.houses.ascendant létezik és típusa „szám, ekliptikai hossz fokokban”. Kevesebb struktúra‑hallucináció, pontosabb híváslánc, lehetőség a válasz validálására a kliens oldalon.

A katalógus fokozatosan nőtt: 285 eszköz a kezdetkor, aztán 624, most már több mint 630 – és a típusos kimenet majdnem teljes lefedettségre jutott (több mint 600 a 630+‑ból). A sémákat nem kézzel írják: a generátor élőben olvassa a /v1/openapi.json‑t a build során, így a drift a REST és az MCP között a felépítés miatt lehetetlen.

A szigorúságnak ára van. Ha egy eszköz closed‑sémát (csak a felsorolt mezőket) hirdet, és a válasz további metaadatot tartalmaz, a strict‑mode kliens elutasítja. A chart‑family eszközöknél pont ezt kaptuk:

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

Ok: a generált Zod‑sémák closed formában voltak, míg a backend tényleges válasza néhány szolgáltatási metadata mezőt tartalmazott, amelyek nincsenek a sémában. A kliens a structuredContent‑et validálta a sémával strict módban, és -32602‑t dobott.

Egy érdekes részlet: Claude Desktop és Cursor bug nem mutatta – ők loose módban vannak, és átengedik a további mezőket. Pont a strict‑mode SDK‑kliensek estek el, amelyek szigorúan validálnak. Vagyis a probléma a legnépszerűbb kliensekben láthatatlan volt, és csak a saját MCP SDK‑ra épülő integrációkban jelentkezett.

A megoldás – nem eldobni a tipizálást, hanem nyitottá tenni a sémákat. Az eszközgenerátorban a kimeneti ZodObject‑sémák passthrough formára konvertálódnak: a deklarált mezők kötelezőek és tipizáltak maradnak, míg a további szolgáltatási mezők átmennek a validáción, anélkül, hogy a hívást megtörnék.

A hosted katalógushoz külön alkalmazott tartalék megoldás – eltávolítani a outputSchema‑t azoknak az eszközöknek a regisztrációjából, ahol a validáció már korábban meghibásodott, hogy a strict kliensek ne essenek el, amíg a sémák teljesen nyitottak nem lesznek. A kompromisszum tudatos: jobb egy helyes hívás kliens‑validáció nélkül, mint egy szigorú hiba.

A tanulság egyszerű: a típusos MCP‑kimenet hasznos, de a válasz sémájának nyitottnak kell lennie a további mezőkre. Az API fejlődik, metaadatok jelennek meg, és egy closed séma minden ilyen kiegészítést breaking change‑dé alakít a strict kliensek számára.

A típusos katalógus mindkét úton elérhető:

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

Vagy a stdio csomag npx -y @astroway/mcp a ASTROWAY_API_KEY kulccsal. Mindkettő ugyanazt a típusos katalógust adja; a teljes kliens útmutató itt: /agent-setup/.