타이핑된 MCP 출력: 600+ 도구가 outputSchema를 가진 이유

도구가 출력 스키마를 선언하면 클라이언트는 호출 전에 응답 형식을 알게 됩니다. 에이전트는 추측하지 않습니다 - chart.houses.ascendant가 존재하고 “숫자, 황도 경도(도 단위)” 타입을 가진다는 것을 볼 수 있습니다. 구조에 대한 환각이 줄고, 호출 체인이 더 정확해지며, 클라이언트 측에서 응답을 검증할 수 있습니다.

카탈로그는 단계적으로 성장했습니다: 시작 시 285개 도구, 그다음 624개, 현재 630개 이상 - 그리고 타입화된 출력은 거의 완전한 커버리지(630개 중 600개 이상)에 도달했습니다. 스키마는 수동으로 작성되지 않습니다: 생성기는 빌드 시 라이브 /v1/openapi.json을 읽으므로 REST와 MCP 간의 드리프트는 구조상 불가능합니다.

엄격함에는 대가가 따릅니다. 도구가 닫힌 스키마(열거된 필드 이상 없음)를 선언하고 응답에 추가 메타데이터가 포함된 경우, strict-mode 클라이언트는 이를 거부합니다. 차트 패밀리 도구에서 바로 이 문제를 포착했습니다:

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

원인: 생성된 Zod 스키마는 closed 형태였지만, 실제 백엔드 응답에는 스키마에 선언되지 않은 여러 서비스 메타데이터 필드가 포함되어 있었습니다. 클라이언트는 strict 모드에서 structuredContent를 스키마와 검증하고 -32602 오류를 발생시켰습니다.

흥미로운 세부 사항: Claude Desktop과 Cursor는 버그를 보여주지 않았습니다 -它们는 loose 모드이며 추가 필드를 통과시킵니다. 엄격하게 검증하는 strict-mode SDK 클라이언트만 실패했습니다. 즉, 문제는 가장 인기 있는 클라이언트에서는 보이지 않고 MCP SDK 위의 사용자 정의 통합에서만 나타났습니다.

해결책은 타이핑을 제거하는 것이 아니라 스키마를 열리게 하는 것입니다. 도구 생성기에서 출력 ZodObject 스키마는 passthrough 형태로 변환됩니다: 선언된 필드는 필수 및 타입화된 상태로 유지되고, 추가 서비스 필드는 호출을 중단하지 않고 검증을 통과합니다.

호스팅된 카탈로그에는 별도의 대안이 적용됩니다 - 스키마가 완전히 열리기 전까지 strict 클라이언트가 실패하지 않도록 검증이 이미 깨진 도구의 outputSchema 등록을 제거합니다. 이것은 의식적인 타협입니다: 엄격한 실패보다 클라이언트 검증 없는 정확한 호출이 더 낫습니다.

교훈은 간단합니다: 타입화된 MCP 출력은 유용하지만 응답 스키마는 추가 필드에 열려 있어야 합니다. API는 진화하고 메타데이터가 나타나며, 닫힌 스키마는 strict 클라이언트에 있어서 모든 추가 사항을 breaking change로 만듭니다.

타입화된 카탈로그는 두 가지 경로로 모두 사용할 수 있습니다:

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

또는 ASTROWAY_API_KEY 키를 사용한 stdio 패키지 npx -y @astroway/mcp. 두 가지 모두 동일한 타입화된 카탈로그를 제공하며, 클라이언트에 대한 전체 가이드는 /agent-setup/에 있습니다.