Typovaný výstup MCP: proč 600+ nástrojů má outputSchema

MCP‑instrument může vrátit cokoliv – protokol nevyžaduje popisovat formu odpovědi. Proto většina serverů vrací agentovi holý JSON a model hádá strukturu z textu. To funguje, dokud se neporuší: agent vezme pole, které neexistuje, nebo špatně interpretuje vnořenost.

Šli jsme přísnou cestou: více než 600 z našich MCP‑instrumentů publikuje outputSchema – strojový schéma odpovědi, vygenerované ze stejného OpenAPI kontraktu jako REST API.

Když instrument oznamuje výstupní schéma, klient zná formu odpovědi před voláním. Agent neháde – vidí, že chart.houses.ascendant existuje a má typ „číslo, ekliptikální délka ve stupních“. Méně halucinací o struktuře, přesnější řetězec volání, možnost validovat odpověď na straně klienta.

Katalog rostl postupně: 285 instrumentů na startu, pak 624, nyní přes 630 – a typovaný výstup se přiblížil téměř k úplnému pokrytí (více než 600 z 630+). Schémata se nepíšou ručně: generátor čte live /v1/openapi.json na buildu, takže drift mezi REST a MCP je podle konstrukce nemožný.

Přísnost má cenu. Když instrument oznamuje closed‑schéma (žádná pole nad vyjmenovanými), a odpověď obsahuje další metadata, strict‑mode klient to odmítne. Na chart‑family instrumentech jsme to zachytili právě tak:

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

Příčina: vygenerovaná Zod‑schémata byla v closed‑formě, ale skutečná odpověď backendu nesla několik servisních metadata‑polí, neoznačených ve schématu. Klient validoval structuredContent proti schématu ve strict‑režimu a vracel -32602.

Zajímavý detail: Claude Desktop a Cursor bug neukazovaly – jsou v loose‑režimu a další pole přeskakují. Padaly právě strict‑mode SDK‑klienti, kteří validují přísně. Takže problém byl neviditelný v nejpopulárnějších klientech a objevil se jen ve vlastních integracích nad MCP SDK.

Řešení – neodstraňovat typizaci, ale udělat schémata otevřenými. V generátoru instrumentů se výstupní ZodObject‑schémata převádějí do passthrough‑formy: oznámená pole zůstávají povinná a typizovaná, a další servisní pole procházejí validací, neporušují volání.

Pro hosted‑katalog je samostatně použit záložní variant – odebrat outputSchema z registrace těch instrumentů, kde byla validace už poškozena, aby strict‑klienti nepadali, dokud nejsou schémata plně otevřená. Kompromis je uvědomělý: lepší korektní volání bez klientské validace než tvrdý selhání.

Lekce je jednoduchá: typovaný výstup MCP je užitečný, ale schéma odpovědi musí být otevřené pro další pole. API se vyvíjí, metadata se objevují, a closed‑schéma převádí každé takové doplnění na breaking change pro strict‑klienty.

Typovaný katalog je dostupný oběma způsoby:

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

Nebo stdio‑balíček npx -y @astroway/mcp s klíčem v ASTROWAY_API_KEY. Oba vrací stejný typovaný katalog; kompletní návod na klienty – na /agent-setup/.