MCP 도구 설계 패턴
— 좋은 도구 vs 나쁜 도구
MCP 서버를 만드는 건 어렵지 않습니다.
AI 에이전트가 제대로 쓸 수 있는 도구를 만드는 게 어렵습니다.
MCP 도구의 품질은
description 한 줄, 스키마 몇 줄에서 결정됩니다.
AI 에이전트는 이 정보만 보고
도구를 이해하고 호출합니다.
좋은 도구는 에이전트가 정확하게 사용하고,
나쁜 도구는 잘못 호출하거나 아예 무시합니다.
1. description — 도구의 운명을 결정하는 한 줄
LLM은 도구의 description을 읽고
“이 도구를 지금 써야 하는가”를 판단합니다.
description이 모호하면 엉뚱한 상황에서 호출되고,
너무 길면 핵심을 놓칩니다.
나쁜 description
“데이터를 처리합니다”
→ 무슨 데이터? 어떻게 처리? 에이전트가 판단 불가
“이 도구는 사용자의 주문 정보를 데이터베이스에서 조회하여 JSON 형식으로 반환하는 도구입니다. 주문 번호를 입력하면 주문 상태, 배송 정보, 결제 정보를 포함한 상세 정보를 확인할 수 있습니다.”
→ 불필요하게 길고 반복적. 핵심이 묻힘
좋은 description
“주문 번호로 주문 상세(상태, 배송, 결제)를 조회합니다.”
→ 무엇을(주문 상세), 어떻게(주문 번호로), 결과가 뭔지(상태, 배송, 결제) 명확
description 작성 원칙
· 한 문장으로 도구의 목적을 설명
· 입력이 무엇인지, 출력이 무엇인지 포함
· 언제 쓰는지 맥락을 포함 (선택, 하지만 권장)
· 구현 세부사항(DB 타입, API 경로)은 제외
· LLM 지시문으로 오해될 수 있는 표현 금지
2. 입력 스키마 — 엄격할수록 안전하다
MCP 도구의 inputSchema는 JSON Schema 형식입니다.
에이전트는 이 스키마를 보고 파라미터를 구성합니다.
나쁜 스키마
· 타입이 any나 string으로만 정의
· 필수/선택 구분이 없음
· 파라미터 설명(description)이 없음
· 유효 범위(enum, min, max)가 없음
좋은 스키마
· 각 파라미터에 정확한 타입 (string, number, boolean)
· required로 필수 파라미터 명시
· 각 파라미터에 description 포함
· enum으로 허용 값 제한 (예: status: [“active”, “inactive”])
· 기본값(default) 제공
스키마가 엄격할수록 에이전트가 올바른 인자를 보내고,
동시에 인젝션 공격의 여지도 줄어듭니다.
3. 단일 책임 — 하나의 도구는 하나의 일만
“주문을 조회하고, 수정하고, 삭제하는 도구”는
하나가 아니라 세 개여야 합니다.
왜 나눠야 하는가
· 권한 분리 — 조회는 허용하되 삭제는 승인 필요
· 에이전트 판단 정확도 — 도구가 하나의 일만 하면 선택이 명확
· 에러 추적 — 어떤 행동에서 문제가 생겼는지 바로 특정
· 감사 로그 — “조회했다”와 “삭제했다”가 구분됨
4. 에러 처리 — 에이전트가 이해할 수 있는 에러
도구가 실패했을 때
에이전트는 에러 메시지를 보고 다음 행동을 결정합니다.
스택트레이스를 돌려주면 에이전트는 아무것도 할 수 없습니다.
나쁜 에러
“Error: ECONNREFUSED 127.0.0.1:5432”
→ 에이전트가 DB 연결 오류를 해결할 수 없음. 내부 구현 노출
좋은 에러
“주문 번호 ORD-12345를 찾을 수 없습니다. 주문 번호를 확인해 주세요.”
→ 에이전트가 사용자에게 재확인 요청 가능
에러 처리 원칙
· 에이전트가 다음 행동을 판단할 수 있는 메시지
· 내부 구현 세부사항(IP, 포트, 스택트레이스) 절대 노출 금지
· 재시도 가능 여부 명시 (일시적 오류 vs 영구적 오류)
· MCP의 isError 플래그를 활용하여 에러 응답 구분
5. 멱등성 — 두 번 호출해도 같은 결과
AI 에이전트는 같은 도구를 여러 번 호출할 수 있습니다.
네트워크 타임아웃으로 재시도하거나,
에이전트 로직이 반복 호출할 수도 있습니다.
조회(GET) 도구는 자연스럽게 멱등하지만,
쓰기 도구는 의도적으로 설계해야 합니다.
멱등성 확보 방법
· 주문 생성 시 idempotency key 파라미터 추가
· 같은 키로 재요청 시 기존 결과 반환 (중복 생성 방지)
· 상태 변경 시 “현재 상태 확인 → 변경”이 아닌 원자적 연산 사용
· description에 멱등성 여부를 명시
6. 응답 설계 — 에이전트가 파싱할 수 있게
도구의 응답은 에이전트의 다음 사고 과정에 들어갑니다.
구조화된 JSON으로 돌려주되,
너무 많은 데이터를 한 번에 보내지 마세요.
응답 설계 원칙
· 필요한 정보만 반환 (전체 레코드를 덤프하지 않기)
· 대량 결과는 페이지네이션 또는 요약 제공
· 민감 정보(비밀번호, 토큰)는 응답에서 제외
· 일관된 응답 구조 유지 (성공/실패 모두 같은 형태)
도구 설계 체크리스트
description이 한 문장으로 도구의 목적, 입력, 출력을 설명하는가?
☐inputSchema에 모든 파라미터의 타입, 필수 여부, 설명이 있는가?
☐하나의 도구가 하나의 일만 하는가? (단일 책임)
☐읽기 도구와 쓰기 도구가 분리되어 있는가?
☐에러 메시지가 에이전트의 다음 행동을 안내하는가?
☐내부 구현 세부사항이 에러 메시지에 노출되지 않는가?
☐쓰기 도구에 멱등성이 확보되어 있는가?
☐응답에 민감 정보가 포함되지 않는가?
☐도구의 품질은 에이전트의 정확도에 직결됩니다.
좋은 도구를 만들면 에이전트가 알아서 잘 쓰고,
나쁜 도구를 만들면 아무리 좋은 모델이라도 실수합니다.
본 글은 리원에이스 기술개발본부가 작성한 기술 콘텐츠입니다. 외부 공유 시 출처를 명시해 주세요.
2026년 8월 19일
리원에이스 기술개발본부