Estructura de salida tipizada de MCP: ¿por qué 600+ herramientas tienen outputSchema

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

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

Cuando el instrumento declara un esquema de salida, el cliente conoce la forma de la respuesta antes de la llamada. El agente no adivina - ve que chart.houses.ascendant existe y tiene tipo «número, longitud eclíptica en grados». Menos alucinaciones sobre la estructura, una cadena de llamadas más precisa, posibilidad de validar la respuesta del lado del cliente.

El catálogo creció paso a paso: 285 instrumentos al inicio, luego 624, ahora más de 630 - y la salida tipada se acercó casi a una cobertura total (más de 600 de 630+). Los esquemas no se escriben a mano: el generador lee en vivo /v1/openapi.json en la compilación, por lo que el drift entre REST y MCP es imposible por construcción.

La estricticidad tiene su precio. Cuando el instrumento declara un esquema closed (ningún campo más allá de los listados), y la respuesta contiene metadatos adicionales, el cliente en modo strict lo rechaza. En los instrumentos chart-family capturamos exactamente eso:

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

Causa: los esquemas Zod generados estaban en forma closed, y la respuesta real del backend incluía varios campos de metadata de servicio, no declarados en el esquema. El cliente validaba structuredContent contra el esquema en modo strict y lanzaba -32602.

Detalle interesante: Claude Desktop y Cursor no mostraban el bug - están en modo loose y pasan los campos adicionales. Caían los clientes SDK en modo strict, que validan de forma rígida. Es decir, el problema era invisible en los clientes más populares y solo aparecía en integraciones propias sobre el SDK MCP.

La solución no es descartar la tipificación, sino hacer los esquemas abiertos. En el generador de instrumentos, los esquemas ZodObject de salida se convierten a forma passthrough: los campos declarados siguen siendo obligatorios y tipados, y los campos de servicio adicionales pasan la validación, sin romper la llamada.

Para el catálogo hosted se aplicó una variante de respaldo: quitar outputSchema del registro de aquellos instrumentos donde la validación ya estaba rota, para que los clientes strict no fallen mientras los esquemas no estén completamente abiertos. El compromiso es consciente: es mejor una llamada correcta sin validación del cliente que un fallo rígido.

Lección simple: la salida tipada de MCP es útil, pero el esquema de respuesta debe estar abierto a campos adicionales. La API evoluciona, aparecen metadatos, y un esquema closed convierte cada adición en un breaking change para los clientes strict.

El catálogo tipado está disponible por ambas vías:

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

O el paquete stdio npx -y @astroway/mcp con la clave en ASTROWAY_API_KEY. Ambos devuelven el mismo catálogo tipado; la guía completa de clientes está en /agent-setup/.