피드로 돌아가기
Dev.toAI/ML
원문 읽기
MCP 서버 도구 호출 성공률 81% 달성과 Schema Description의 중요성 검증
Schema descriptions are load-bearing: why missing parameter descriptions break MCP clients
AI 요약
Context
Model Context Protocol(MCP) 서버의 도구 및 리소스 동작을 검증하는 자동화된 테스트 환경의 부재로 인해 서버 구현물의 신뢰성 확보에 어려움이 있었음. 특히 LLM이 도구를 호출할 때 참조하는 JSON Schema의 설명(description) 필드가 누락될 경우, 클라이언트가 유효한 인자를 생성하지 못해 시스템 호출이 실패하는 병목 현상이 발생함.
Technical Solution
- MCP 서버의 모든 Tool, Resource, Prompt를 열거하고 자동 생성된 인자로 호출을 시도하는 mcp-probe CLI 설계
- 호출 실패 시 전송된 JSON 요청 전문과 서버 응답을 매칭하여 서버 버그와 클라이언트 생성 인자 오류를 분리하는 진단 로직 구현
- server-filesystem의 Sandbox 제약을 해결하기 위해 list_allowed_directories API를 선행 호출하여 유효 경로를 동적으로 확보하는 경로 정규화 메커니즘 적용
- JSON Schema Enum이 부재한 경우 Description 텍스트 내에서 허용 값(Allow-list)을 파싱하여 인자를 생성하는 Fallback 전략 수립
- Schema Description의 존재 여부를 Load-bearing 요소로 정의하여, 설명 누락 시 자동화 도구 및 LLM의 인자 추론이 불가능함을 증명하는 검증 체계 구축
실천 포인트
- MCP 서버 배포 전 모든 Input Schema의 Property에 명확한 description 필드 추가 여부 확인 - 도구 호출 실패 시 Client-side에서 전송한 Payload를 로깅하여 서버 오류와 인자 생성 오류를 구분하는 디버깅 파이프라인 구축 - 파일 시스템 접근 도구 설계 시 서버의 Sandbox 설정과 클라이언트의 경로 생성 로직 간의 일관성 검증