AI가 외면하는 도구의 공통점, MCP 설계 교훈

잘 만든 API를 그대로 감싸면 AI 에이전트가 알아서 잘 쓸 것이다 — 이 통념이 실전에서 깨졌다. 한 개발자가 자신의 MCP(Model Context Protocol) 도구를 라이벌 AI에 붙여 검증한 뒤 정리한 설계 교훈이 공개됐다.

무슨 일인가 / 배경

웹훅을 안정적인 주소로 받아 로컬 앱에 재생해주는 서비스 플러리포트(FlurryPORT)를 만든 진 빌(Gene Beal)은, 자사 MCP 구현을 완성했다고 믿고 다른 코딩 AI에 연결해 초보 사용자처럼 프롬프트를 넣어봤다. 결과는 뜻밖이었다. AI는 정작 제공된 도구를 놔두고, 웹훅을 주고받을 다른 방법을 이것저것 끌어다 쓰려 했다. 그는 테스트를 멈추고 AI에게 직접 '이 구현을 어떻게 고치면 좋겠냐'고 물었고, 거기서 나온 요구사항으로 도구를 다시 설계했다.

핵심 짚어보기

정리된 교훈은 실무에 곧바로 옮길 수 있을 만큼 구체적이다. 첫째, 안내 문장보다 '어포던스', 즉 호출할 도구 자체가 훨씬 강력하다. '요청 속도를 조절하라'는 문단은 무시됐지만, 남은 횟수를 알려주는 작은 도구는 매 배치마다 호출됐다. 둘째, 응답에는 남은 한도·다음 액션(라벨·비용·효과·URL)·경고를 구조화된 필드로 담아라. 밋밋한 숫자 하나는 모델에게 행동 근거를 주지 못한다. 셋째, 문장이 아니라 안정적인 상태 코드로 말하라. 에이전트는 문장 표현이 아니라 'at_cap' 같은 코드에 반응한다. '에러 문자열은 UI, 코드는 API'라는 정리가 인상적이다. 넷째, 부분 성공을 만들지 마라. 10건 중 7건만 보내면 에이전트가 사용자에게 구구절절 설명해야 하는 '설명 부채'가 생긴다. 처리 전에 요청 전체를 예산과 대조해 깔끔하게 거절하는 편이 낫다. 다섯째, 놓치면 안 되는 알림은 단발 이벤트가 아니라 매 응답에 남는 지속 필드로 둬야 한다. 마지막으로 그는 만들기 전에 에이전트에게 설계를 리뷰시키는 것이 최고의 검수라고 강조한다. 실측 개선치도 붙였다. 80건 대량 전송 중 거절이 약 50건에서 0건으로, 가입 후 재적응 시간이 약 4분에서 21초로 줄었다.

1인기업 실전 적용 포인트

• 자동화 도구·API 응답에 '남은 한도, 다음에 할 수 있는 액션, 경고'를 JSON 필드로 넣어 에이전트가 스스로 판단하게 하라.
• 도구 설명문에 '이걸 먼저 호출'처럼 라우팅 힌트를 직접 써라. 발견성은 문서가 아니라 설명문에서 나온다.
• 실패는 부분 처리하지 말고 '최대 N건까지'라고 통째로 거절해, 뒷정리 로직과 사용자 혼란을 줄여라.
• 도구를 배포하기 전에 클로드 코드(Claude Code) 같은 에이전트에게 '이 도구 쓰기 편하냐'고 물어 스키마를 먼저 다듬어라.

전망 / 주의점

MCP 생태계가 커지면서 '도구를 얼마나 많이 노출하느냐'보다 '에이전트가 실제로 집어 드는 모양으로 설계했느냐'가 경쟁력이 되고 있다. 사람용 UI 감각으로 만든 도구는 에이전트 앞에서 외면당하기 쉽다는 점을 이 사례가 분명히 보여준다.

출처: HN (https://blog.spill.coffee/p/trust-the-harbor-pilot)