해피 패스 편향
대부분의 MCP 서버 README를 읽어 보시면 이상적인 조건에서 서버를 어떻게 설정하고 무엇을 할 수 있는지를 정확하게 배우실 수 있습니다. "어떤 SQL 데이터베이스든 쿼리할 수 있습니다." "파일을 읽고 쓸 수 있습니다." "웹을 검색할 수 있습니다." 이러한 기능 설명은 정확하지만 불완전합니다. 일이 어그러질 때 무슨 일이 벌어지는지에 대해서는 알려 주지 않기 때문입니다.
1,000만 행짜리 테이블에 쿼리를 던지면 어떻게 될까요? 쿼리 도중에 데이터베이스 연결이 끊기면 어떻게 될까요? 어느 정도 크기의 파일이 처리하기에 너무 큰 걸까요? 실제로 지원되는 SQL 방언은 무엇입니까? 이러한 질문에 대한 답은 보통 고통스러운 시행착오를 통해 발견됩니다.
실패 문서가 담아야 할 내용
알려진 한계: "최대 결과 집합 크기는 10,000행입니다. 더 큰 쿼리는 잘립니다." "바이너리 파일은 지원되지 않으며 오류를 반환합니다." 이러한 정보는 사용자가 실패를 통해 한계를 발견하느라 시간을 낭비하지 않도록 기대치를 명확히 잡아 줍니다.
일반적인 오류 시나리오: "'connection timeout'이 표시되면 데이터베이스 서버에 접근할 수 없을 수 있습니다. 설정의 호스트와 포트가 올바른지 확인하십시오." 이런 정보는 흔한 오류에 대해 가장 가능성 높은 원인을 제시함으로써 디버깅 시간을 줄여 줍니다.
엣지 케이스: "BLOB 컬럼이 포함된 쿼리는 바이너리 데이터를 JSON으로 직렬화할 수 없기 때문에 실패합니다." "유니코드 문자가 포함된 파일 경로는 Windows에서 동작하지 않을 수 있습니다." 이런 정보는 가장 큰 좌절감을 안기는 특정 상황을 미리 막아 줍니다.
신뢰의 효과
직관에 반하는 이야기지만, 실패를 문서화하면 신뢰가 쌓입니다. README가 솔직하게 "이 서버는 1만 행 미만의 쿼리에는 훌륭하게 동작하지만, 그보다 큰 결과 집합에는 어려움을 겪습니다"라고 말하면, 무한한 능력을 주장하는 README보다 그 작성자를 더 신뢰하시게 됩니다. 또한 더 잘 알고 도입을 결정하실 수 있게 됩니다.
좋은 실패 문서는 개발자 경험에 대한 투자입니다. 도구의 한계를 이해하시는 사용자는 그 한계 안에서 도구를 사용하시고 좋은 경험을 하시게 됩니다. 한계를 실패를 통해 알게 되는 사용자는 나쁜 경험을 하시게 되고 다른 대안으로 옮겨 가실 가능성이 높습니다.