Typisierte Ausgabe MCP: warum 600+ Werkzeuge ein outputSchema haben

MCP‑Instrument kann beliebiges zurückgeben – das Protokoll verlangt nicht, die Form der Antwort zu beschreiben. Deshalb geben die meisten Server dem Agenten nacktes JSON zurück, und das Modell errät die Struktur aus dem Text. Das funktioniert, bis es bricht: Der Agent greift auf ein Feld zu, das nicht existiert, oder interpretiert die Verschachtelung falsch.

Wir haben den strengen Weg gewählt: über 600 unserer MCP‑Instrumente veröffentlichen outputSchema – ein maschinelles Antwort‑Schema, das aus demselben OpenAPI‑Vertrag wie die REST‑API generiert wurde.

Wenn ein Instrument ein Ausgangsschema deklariert, weiß der Client die Form der Antwort bereits vor dem Aufruf. Der Agent muss nicht raten – er sieht, dass chart.houses.ascendant existiert und den Typ „Zahl, ekliptikale Länge in Grad“ hat. Weniger Halluzinationen über die Struktur, genauere Aufrufkette, Möglichkeit, die Antwort clientseitig zu validieren.

Der Katalog ist schrittweise gewachsen: 285 Instrumente zu Beginn, dann 624, jetzt über 630 – und die typisierte Ausgabe hat fast die vollständige Abdeckung erreicht (über 600 von 630+). Schemas werden nicht von Hand geschrieben: Der Generator liest live /v1/openapi.json beim Build, sodass ein Drift zwischen REST und MCP per Konstruktion unmöglich ist.

Strenge Typisierung hat ihren Preis. Wenn ein Instrument ein closed‑Schema (keine Felder außer den aufgelisteten) deklariert und die Antwort zusätzliche Metadaten enthält, lehnt der strict‑Mode‑Client das ab. Bei chart‑family‑Instrumenten haben wir genau das erwischt:

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

Ursache: Die generierten Zod‑Schemas waren im closed‑Modus, während die tatsächliche Backend‑Antwort mehrere service‑metadata‑Felder enthielt, die im Schema nicht deklariert waren. Der Client validierte structuredContent gegen das Schema im strict‑Modus und warf -32602.

Interessanter Hinweis: Claude Desktop und Cursor zeigten den Bug nicht – sie laufen im loose‑Modus und lassen zusätzliche Felder durch. Es waren die strict‑Mode‑SDK‑Clients, die hart validierten, die abstürzten. Das Problem war also in den populärsten Clients unsichtbar und trat nur in eigenen Integrationen über das MCP‑SDK auf.

Die Lösung – die Typisierung nicht verwerfen, sondern die Schemas offen machen. Im Instrument‑Generator werden die Ausgangs‑ZodObject‑Schemas in eine passthrough‑Form konvertiert: deklarierte Felder bleiben verpflichtend und typisiert, während zusätzliche service‑Felder die Validierung passieren, ohne den Aufruf zu brechen.

Für den gehosteten Katalog wird ein separater Fallback verwendet – das outputSchema aus der Registrierung jener Instrumente entfernen, bei denen die Validierung bereits gebrochen war, damit strict‑Clients nicht abstürzen, bis die Schemas vollständig offen sind. Der Kompromiss ist bewusst: ein korrekter Aufruf ohne clientseitige Validierung ist besser als ein harter Fehler.

Die Lehre ist einfach: Die typisierte Ausgabe von MCP ist nützlich, aber das Antwort‑Schema muss für zusätzliche Felder offen sein. Die API entwickelt sich weiter, Metadaten tauchen auf, und ein closed‑Schema macht jede solche Ergänzung zu einem breaking change für strict‑Clients.

Der typisierte Katalog ist auf beiden Wegen verfügbar:

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

Oder das stdio‑Paket npx -y @astroway/mcp mit dem Schlüssel in ASTROWAY_API_KEY. Beide liefern denselben typisierten Katalog; die vollständige Anleitung zu den Clients findest du unter /agent-setup/.