型付けされたMCP出力: 600以上のツールがoutputSchemaを持つ理由

MCPツールは何でも返せるため、プロトコルは応答の形式を記述することを要求しません。そのため、ほとんどのサーバーはエージェントに生のJSONを返し、モデルはテキストから構造を推測します。これは、エージェントが存在しないフィールドを取得したり、ネストを誤って解釈したりするまでは機能します。

私たちは厳格な道を選びました。600以上のMCPツールが、REST APIと同じOpenAPIコントラクトから生成された機械可読な応答スキーマであるoutputSchemaを公開しています。

ツールが出力スキーマを宣言すると、クライアントは呼び出し前に応答の形式を知ることができます。エージェントは推測せず、chart.houses.ascendantが存在し、「数値、度数での黄道経度」という型を持つことを確認します。構造に関する幻覚が減り、より正確な呼び出しチェーンが実現し、クライアント側で応答を検証する機能が得られます。

カタログは段階的に成長しました。開始時には285ツール、次に624、現在は630以上となり、型付き出力もほぼ完全にカバーされるようになりました（630以上のうち600以上）。スキーマは手書きではなく、ビルド時にジェネレーターがライブの/v1/openapi.jsonを読み込むため、RESTとMCP間のドリフトは構造上不可能です。

厳格さには代償が伴います。ツールがクローズドスキーマ（リストされたフィールド以外のフィールドは許可しない）を宣言し、応答に余分なメタデータが含まれている場合、厳格モードのクライアントはそれを拒否します。チャートファミリーツールで、まさにこの問題に遭遇しました。

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

原因は、生成されたZodスキーマがクローズド形式であり、実際のバックエンド応答にはスキーマで宣言されていないいくつかのサービスメタデータフィールドが含まれていたためです。クライアントはstructuredContentを厳格モードでスキーマに対して検証し、-32602を返しました。

興味深いニュアンスとして、Claude DesktopとCursorはこのバグを示しませんでした。これらはルーズモードであり、追加フィールドをスキップするためです。厳密に検証する厳格モードのSDKクライアントだけが失敗しました。つまり、この問題は最も人気のあるクライアントでは見えず、MCP SDK上の独自の統合でのみ表面化しました。

解決策は、型付けを捨てるのではなく、スキーマをオープンにすることです。ツールジェネレーターでは、出力ZodObjectスキーマがパストスルー形式に変換されます。これにより、宣言されたフィールドは必須かつ型付けされたままですが、追加のサービスフィールドは呼び出しを失敗させることなく検証を通過します。

ホスト型カタログでは、別途代替策が適用されました。スキーマが完全にオープンになるまで厳格なクライアントが失敗しないように、すでに検証が壊れていたツールからoutputSchemaの登録を解除しました。これは意図的な妥協です。厳格な失敗よりも、クライアント側での検証なしで正しい呼び出しができる方が良いからです。

教訓はシンプルです。MCPの型付き出力は有用ですが、応答スキーマは追加フィールドに対してオープンである必要があります。APIは進化し、メタデータは出現します。クローズドスキーマは、そのような追加を厳格なクライアントにとっての破壊的変更に変えてしまいます。

型付きカタログは両方の方法で利用できます。

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

または、ASTROWAY_API_KEYにキーを設定したstdioパッケージnpx -y @astroway/mcpを使用します。どちらも同じ型付きカタログを提供します。クライアントに関する完全なガイドは/agent-setup/にあります。