MCP typed output: why 600+ tools have outputSchema

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

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

Khi công cụ công bố sơ đồ đầu ra, client biết dạng phản hồi trước khi gọi. Agent không đoán - nó thấy rằng chart.houses.ascendant tồn tại và có kiểu «số, kinh độ ecliptic tính bằng độ». Ít ảo tưởng về cấu trúc hơn, chuỗi gọi chính xác hơn, khả năng xác thực phản hồi ở phía client.

Danh mục đã phát triển theo giai đoạn: 285 công cụ lúc bắt đầu, sau đó 624, hiện nay hơn 630 - và đầu ra có kiểu gần như phủ toàn bộ (hơn 600 trong hơn 630). Các sơ đồ không được viết bằng tay: trình tạo đọc live /v1/openapi.json trên build, vì vậy sự lệch giữa REST và MCP là không thể xảy ra.

Sự nghiêm ngặt có cái giá của nó. Khi công cụ công bố closed-scheme (không có trường nào ngoài những đã liệt kê), và phản hồi chứa thêm metadata, client ở chế độ strict sẽ từ chối. Trên các công cụ chart-family chúng tôi đã bắt gặp điều này:

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

Nguyên nhân: các Zod-scheme được tạo ra ở dạng closed, nhưng phản hồi thực tế của backend mang một vài trường metadata dịch vụ, không được khai báo trong sơ đồ. Client xác thực structuredContent so với sơ đồ ở chế độ strict và trả về -32602.

Một chi tiết thú vị: Claude Desktop và Cursor bug không hiển thị - chúng ở chế độ loose và cho phép các trường bổ sung. Chỉ các client SDK ở chế độ strict, những người xác thực chặt chẽ, mới gặp lỗi. Vì vậy vấn đề này không thấy ở các client phổ biến và chỉ xuất hiện trong các tích hợp riêng của bạn trên MCP SDK.

Giải pháp - không loại bỏ kiểu, mà làm cho các sơ đồ mở. Trong trình tạo công cụ, các ZodObject-scheme đầu ra được chuyển sang dạng passthrough: các trường đã khai báo vẫn bắt buộc và có kiểu, còn các trường dịch vụ bổ sung sẽ qua xác thực mà không phá vỡ cuộc gọi.

Đối với hosted-catalog, một phương án dự phòng được áp dụng riêng - loại bỏ outputSchema khỏi đăng ký các công cụ mà việc xác thực đã bị hỏng, để các client strict không bị sập cho tới khi các sơ đồ được mở hoàn toàn. Thỏa hiệp này có ý nghĩa: tốt hơn một cuộc gọi đúng mà không có xác thực client, hơn là lỗi nghiêm trọng.

Bài học đơn giản: đầu ra có kiểu của MCP hữu ích, nhưng sơ đồ phản hồi phải mở cho các trường bổ sung. API liên tục phát triển, metadata xuất hiện, và closed-scheme biến mỗi bổ sung thành breaking change cho các client strict.

Danh mục có kiểu có sẵn qua cả hai cách:

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

Hoặc gói stdio npx -y @astroway/mcp với khóa trong ASTROWAY_API_KEY. Cả hai đều trả về cùng một danh mục có kiểu; hướng dẫn đầy đủ về client - tại /agent-setup/.