Saída MCP tipada: por que 600+ ferramentas têm outputSchema

MCP-instrumento pode devolver qualquer coisa – o protocolo não exige descrever a forma da resposta. Por isso, a maioria dos servidores devolve ao agente um JSON puro, e o modelo adivinha a estrutura a partir do texto. Isto funciona até falhar: o agente tenta aceder a um campo que não existe ou interpreta mal o aninhamento.

Nós seguimos o caminho estrito: mais de 600 dos nossos instrumentos MCP publicam outputSchema – um esquema de resposta máquina, gerado a partir do mesmo contrato OpenAPI que a REST API.

Quando um instrumento declara o esquema de saída, o cliente conhece a forma da resposta antes da chamada. O agente não adivinha – ele vê que chart.houses.ascendant existe e tem o tipo «número, longitude eclíptica em graus». Menos alucinações sobre a estrutura, cadeia de chamadas mais precisa, possibilidade de validar a resposta no lado do cliente.

O catálogo cresceu passo a passo: 285 instrumentos no início, depois 624, agora mais de 630 – e a saída tipada chegou quase a cobrir tudo (mais de 600 de 630+). Os esquemas não são escritos à mão: o gerador lê o live /v1/openapi.json no build, por isso o drift entre REST e MCP é impossível por construção.

A rigidez tem um preço. Quando um instrumento declara um esquema closed (nenhum campo além dos listados), e a resposta contém metadados adicionais, o cliente strict-mode rejeita isso. Nos instrumentos chart-family nós capturámos exatamente isso:

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

Causa: os esquemas Zod gerados estavam em forma closed, e a resposta real do backend continha vários campos de metadata de serviço, não declarados no esquema. O cliente validava structuredContent contra o esquema em modo strict e lançava -32602.

Um detalhe interessante: Claude Desktop e Cursor bug não mostravam – eles estão em modo loose e deixam passar campos adicionais. Falhavam apenas os clientes SDK strict-mode, que validam rigidamente. Ou seja, o problema era invisível nos clientes mais populares e surgia apenas nas integrações próprias sobre o MCP SDK.

A solução – não descartar a tipagem, mas tornar os esquemas abertos. No gerador de instrumentos, os esquemas ZodObject de saída são convertidos para a forma passthrough: os campos declarados permanecem obrigatórios e tipados, e os campos de serviço adicionais passam pela validação, sem quebrar a chamada.

Para o catálogo hosted foi aplicado um caminho alternativo – remover outputSchema do registo desses instrumentos, onde a validação já estava quebrada, para que os clientes strict não falhem enquanto os esquemas não estejam totalmente abertos. O compromisso é consciente: melhor uma chamada correta sem validação do cliente do que uma falha rígida.

A lição é simples: a saída tipada do MCP é útil, mas o esquema de resposta deve ser aberto a campos adicionais. A API evolui, a metadata aparece, e um esquema closed transforma cada adição num breaking change para clientes strict.

O catálogo tipado está disponível por ambos os caminhos:

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

Ou o pacote stdio npx -y @astroway/mcp com a chave em ASTROWAY_API_KEY. Ambos devolvem o mesmo catálogo tipado; o guia completo sobre clientes – em /agent-setup/.