Typizowany output MCP: dlaczego 600+ narzędzi ma outputSchema

MCP-narzędzie może zwrócić cokolwiek - protokół nie wymaga opisywania formy odpowiedzi. Dlatego większość serwerów zwraca agentowi czysty JSON, a model zgaduje strukturę z tekstu. To działa, aż się zepsuje: agent bierze pole, którego nie ma, lub błędnie interpretuje zagnieżdżenie.

Poszliśmy ścieżką ścisłą: ponad 600 naszych narzędzi MCP publikuje outputSchema - maszynowy schemat odpowiedzi, wygenerowany z tego samego kontraktu OpenAPI, co REST API.

Gdy narzędzie deklaruje schemat wyjściowy, klient zna format odpowiedzi przed wywołaniem. Agent nie zgaduje - widzi, że chart.houses.ascendant istnieje i ma typ ‘liczba, długość ekliptyczna w stopniach’. Mniej halucynacji dotyczących struktury, dokładniejsza sekwencja wywołań, możliwość walidacji odpowiedzi po stronie klienta.

Katalog rozwijał się stopniowo: 285 narzędzi na starcie, potem 624, teraz ponad 630 - i typizowane wyjście niemal w pełni objęło pokrycie (ponad 600 z 630+). Schematy nie są pisane ręcznie: generator odczytuje żywe /v1/openapi.json podczas budowy, więc dryf między REST a MCP jest niemożliwy z konstrukcji.

Ścisłość ma swoją cenę. Gdy narzędzie deklaruje zamknięty schemat (żadnych pól poza wymienionymi), a odpowiedź zawiera dodatkowe metadane, klient w trybie strict odrzuca to. W narzędziach z rodziny chart trafiliśmy dokładnie na to:

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

Powód: wygenerowane schematy Zod były w formie zamkniętej, ale faktyczna odpowiedź backendu zawierała kilka służbowych pól metadata, nie zadeklarowanych w schemacie. Klient walidował structuredContent przeciwko schematowi w trybie strict i rzucał -32602.

Ciekawa niuans: Claude Desktop i Cursor nie pokazywały błędu - one są w trybie loose i dodatkowe pola przepuszczają. Padły tylko klienty SDK w trybie strict, które walidują ścisło. Czyli problem był niewidoczny w najpopularniejszych klientach i wyrwał się tylko w własnych integracjach na szczycie MCP SDK.

Rozwiązaniem nie jest porzucenie typowania, ale uczynienie schematów otwartymi. W generatorze narzędzi wyjściowe schematy ZodObject są konwertowane do formy passthrough: zadeklarowane pola pozostają obowiązkowe i typowane, a dodatkowe służbowe pola przechodzą walidację, nie psując wywołania.

Dla hostowanego katalogu osobno zastosowano zapasowe rozwiązanie - usunięcie outputSchema z rejestracji tych narzędzi, gdzie walidacja i tak była zepsuta, aby klienci strict nie padali, dopóki schematy nie są w pełni otwarte. Świadomy kompromis: lepiej poprawne wywołanie bez walidacji po stronie klienta niż twardy crash.

Lekcja prosta: typizowane wyjście MCP jest użyteczne, ale schemat odpowiedzi musi być otwarty na dodatkowe pola. API ewoluują, metadane pojawiają się, a zamknięty schemat zamienia każde takie dodanie na breaking change dla klientów strict.

Typizowany katalog jest dostępny oboma drogami:

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

Lub pakiet stdio npx -y @astroway/mcp z kluczem w ASTROWAY_API_KEY. Oba dostarczają ten sam typizowany katalog; pełny przewodnik po klientach - na /agent-setup/.