Типізований вивід MCP: чому 600+ інструментів мають outputSchema

MCP-інструмент може повернути що завгодно - протокол не вимагає описувати форму відповіді. Тому більшість серверів віддають агенту голий JSON, а модель вгадує структуру з тексту. Це працює, поки не ламається: агент бере поле, якого немає, або неправильно інтерпретує вкладеність.

Ми пішли строгим шляхом: понад 600 з наших MCP-інструментів публікують outputSchema - машинну схему відповіді, згенеровану з того самого OpenAPI-контракту, що й REST API.

Коли інструмент оголошує вихідну схему, клієнт знає форму відповіді до виклику. Агент не вгадує - він бачить, що chart.angles.asc існує і має тип «обʼєкт зі знаком і градусом». Менше галюцинацій про структуру, точніший ланцюжок викликів, можливість валідувати відповідь на боці клієнта.

Каталог виріс поетапно: 285 інструментів на старті, потім 624, зараз понад 630 - і типізований вивід підтягнувся майже до повного покриття (понад 600 з 630+). Схеми не пишуться руками: генератор читає live /v1/openapi.json на білді, тому drift між REST і MCP неможливий за побудовою.

Строгість має ціну. Коли інструмент оголошує closed-схему (жодних полів понад перелічені), а відповідь містить додаткову метадату, strict-mode клієнт це відхиляє. На chart-family інструментах ми впіймали саме це:

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

Причина: згенеровані Zod-схеми були в closed-формі, а фактична відповідь бекенда несла кілька службових metadata-полів, не оголошених у схемі. Клієнт валідував structuredContent проти схеми в strict-режимі і кидав -32602.

Цікавий нюанс: Claude Desktop і Cursor баг не показували - вони в loose-режимі і додаткові поля пропускають. Падали саме strict-mode SDK-клієнти, які валідують жорстко. Тобто проблема була невидима в найпопулярніших клієнтах і виринала тільки у власних інтеграціях поверх MCP SDK.

Рішення - не викидати типізацію, а зробити схеми відкритими. У генераторі інструментів вихідні ZodObject-схеми переводяться в passthrough-форму: оголошені поля лишаються обовʼязковими й типізованими, а додаткові службові поля проходять валідацію, не валлячи виклик.

Для hosted-каталогу окремо застосований запасний варіант - зняти outputSchema з реєстрації тих інструментів, де валідація і так була зламана, щоб strict-клієнти не падали, поки схеми не відкриті повністю. Компроміс усвідомлений: краще коректний виклик без клієнтської валідації, ніж жорсткий збій.

Урок простий: типізований вивід MCP корисний, але схема відповіді має бути відкритою на додаткові поля. API еволюціонує, метадата зʼявляється, і closed-схема перетворює кожне таке доповнення на breaking change для strict-клієнтів.

Типізований каталог доступний обома шляхами:

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

Або stdio-пакет npx -y @astroway/mcp з ключем у ASTROWAY_API_KEY. Обидва віддають той самий типізований каталог; повний гайд по клієнтах - на /agent-setup/.