본문으로 건너뛰기

커뮤니티

팁 운영진 번역

Model Context Protocol 문서: MCP 클라이언트를 위한 도구 관리 모범 사례

리퀘오 운영팀

이 글은 Model Context Protocol 문서의 '클라이언트 모범 사례'를 한국어로 옮긴 것이다. MCP 호스트 애플리케이션을 만들면서 수백, 수천 개의 도구를 다뤄야 하는 개발자에게 컨텍스트 낭비와 지연을 줄이는 두 가지 패턴을 설명한다.

1. 문제: 도구를 한꺼번에 다루는 방식의 한계

에이전트 같은 MCP 호스트가 여러 서버에 연결해 도구가 많아지면, 모든 도구 정의를 대화 시작 시 모델 컨텍스트에 넣는 방식은 토큰을 낭비하고 지연을 늘리며 모델 성능을 떨어뜨린다. 도구를 연속 호출할 때 큰 중간 결과가 모델을 거쳐 흐르는 것도 문제를 키운다. 이를 해결하는 패턴이 두 가지다. 도구 정의가 언제 컨텍스트에 들어오는지를 제어하는 점진적 발견(progressive discovery)과, 도구가 어떻게 호출되는지를 제어하는 프로그래밍 방식 도구 호출(programmatic tool calling)이다.

2. 점진적 도구 발견

호스트는 평소처럼 tools/list로 도구 정의를 가져오되 모델 컨텍스트에 바로 넣지 않는다. 대신 가벼운 search_tools 메타 도구를 모델에 제공하고, 필요할 때만 전체 정의를 컨텍스트에 넣는다. 도구 정의가 컨텍스트 창의 상당 부분을 차지하기 시작하면 점진적 발견으로 전환하는 것이 좋다. 컨텍스트 창의 1~5% 같은 비율로 임계값을 두고, 임계값에 도달하면 전환하는 방식을 권장한다.

3. 검색 전략 선택

- 키워드 기반: BM25나 정규식 매칭. 단순하고 효과적이며 설명이 잘 된 도구 이름에 특히 유용하다.
- 임베딩 기반: 도구 설명에 대한 벡터 유사도 검색. 동의어와 의미 기반 매칭에 강하다.
- 서브에이전트 기반: Claude Haiku나 Gemini Flash 같은 작고 빠른 보조 모델이 도구를 고른다. 성능은 좋지만 비용이 더 들 수 있다.
- 하이브리드: 키워드와 임베딩 순위를 함께 점수화하거나 용도·질의에 따라 전략을 달리한다.

OpenAI와 Anthropic처럼 일부 모델 제공자는 도구 검색을 기본 지원한다. 제공자가 지원하면 자체 구현보다 플랫폼 기능을 우선 고려하고, 특화된 검색 로직(도메인별 순위, 접근 제어 필터링 등)이 필요할 때 직접 구현한다.

4. 검색 기반 3계층 구현

계층 1, 카탈로그: search_tools가 자연어 질의를 받아 일치하는 도구 이름과 한 줄 설명만 돌려준다.
search_tools({ query: "update salesforce record" })

계층 2, 조회: 후보를 찾으면 해당 도구 하나의 전체 정의(입력·출력 스키마, 문서)만 가져온다.
get_tool_details({ name: "salesforce_updateRecord" })

계층 3, 실행: 필요한 정의만 불러온 상태에서 모델이 도구를 호출한다. 이 패턴은 토큰 사용을 크게 줄이고, 모델이 수백 개의 무관한 도구 대신 소수의 관련 도구에 집중하게 해 선택 정확도를 높인다. 임베딩이나 서브에이전트 등 다른 전략도 같은 계층 원칙을 따르되 카탈로그 계층의 검색 방식만 바꾼다.

5. 동적 서버 관리

점진적 발견은 개별 도구를 넘어 서버 전체에도 적용된다. 호스트는 사용 가능한 서버와 그 개요를 레지스트리로 유지하고, 모델이 필요하다고 판단할 때만 연결하며, 더 이상 필요 없는 서버는 연결을 끊어 컨텍스트를 확보한다. 사용자 의도를 미리 알 수 없는 범용 에이전트에 특히 잘 맞는다. 에이전트 스킬과 결합하면 스킬 파일이 필요한 MCP 서버를 선언하고, 해당 스킬이 호출될 때만 연결하도록 할 수 있다.

6. 구현 지침

- 여러 상세 수준 제공: 이름만, 이름과 설명, 전체 스키마 중에서 모델이 고르게 한다.
- 도구 정의 캐시: 서버에서 한 번 가져온 정의는 호스트 측에 저장해, 다시 넣을 때 tools/list를 또 호출하지 않게 한다. 모델 컨텍스트에 현재 무엇이 있는지와는 별개다.
- list_changed 시 갱신: 서버가 notifications/tools/list_changed를 보내면 검색 카탈로그를 다시 색인한다.
- 서버별 도구 묶음: 도구를 출처 서버별로 정리해 모델이 관련 기능을 함께 추론하게 한다.

7. 캐싱

tools/list 같은 목록 결과와 server/discover, resources/read 결과에는 ttlMs와 cacheScope 힌트가 붙는다. 명세의 캐싱 규칙을 따른다. 특히 list_changed 알림이 오면 TTL이 남아 있어도 캐시된 목록을 오래된 것으로 취급한다.

8. 프롬프트 캐싱과의 상호작용

대부분의 제공자는 tools 배열을 포함한 프롬프트 접두사를 캐시한다. 대화 중간에 도구 정의를 더하거나 빼면 이 캐시가 무효화되고, 그 미스 비용이 제거한 정의보다 클 수 있다. 캐시를 지키려면 새로 발견한 정의를 tools 배열 재정렬 없이 캐시 경계 뒤에 덧붙이거나, 모든 호출을 단일하고 안정적인 call_tool({name, args}) 메타 도구로 보내 배열이 바뀌지 않게 한다. 서버 연결 해제는 매 턴이 아니라 대화 경계에서 처리한다. 쓰는 제공자의 프롬프트 캐싱 문서도 함께 확인한다.

9. 프로그래밍 방식 도구 호출(코드 모드)

직접 호출은 매번 왕복이다. 모델이 호출을 만들고, 클라이언트가 실행하고, 전체 결과가 모델 컨텍스트로 돌아온다. 여러 도구를 연쇄해야 할 때 중간 결과가 모두 모델을 거치며 토큰과 지연을 늘린다. 프로그래밍 방식 도구 호출은 모델이 도구를 호출하는 코드를 작성하게 하고, 코드는 샌드박스에서 실행되며 최종 결과만 모델로 돌아간다. 강력하지만 클라이언트가 샌드박스 환경을 구현해야 한다.

10. 동작 방식

호스트는 MCP 도구 스키마를 샌드박스 안에서 쓸 수 있는 타입 지정 API로 변환한다. 도구에 outputSchema가 있으면 LogEntry 같은 정확한 반환 타입을 만들 수 있다. 없으면 any나 string 같은 일반 타입으로 받아 비정형 출력을 뒤 단계에서 처리하거나(근본 해결은 서버 작성자가 outputSchema를 제공하는 것이다), 루프 밖 단일 호출에 한해 빠른 모델로 타입 결과를 추출하는 헬퍼를 쓸 수 있다. 이 헬퍼는 샌드박스가 네트워크를 열지 않도록 호스트가 중개하며, 호출당 지연이 늘고 필드를 환각하거나 누락할 수 있어 사용 전에 타입과 대조해 검증해야 한다.

모델은 이 API에 맞춰 스크립트 하나를 작성한다. 예를 들어 '지난 한 시간의 오류 로그를 찾아 고유 오류마다 티켓을 생성'하는 작업에서 직접 호출은 수천 개 로그가 모델 컨텍스트를 거치지만, 코드 모드에서는 샌드박스 안에서 필터링과 중복 제거를 하고 티켓 생성까지 처리한다. 샌드박스 안의 함수 호출은 가로채여 호스트 브로커를 통해 해당 MCP 서버로 전달되고, 로그 데이터와 티켓 생성은 모델 컨텍스트를 거치지 않고 서버 간에 직접 흐른다. 모델에는 console.log 출력인 요약 한 줄만 돌아간다.

11. 샌드박스 선택

언어와 격리 수준에 따라 선택이 달라진다. 아래는 예시일 뿐이며 사용 사례에 맞는 성숙도를 따로 평가해야 한다.
- JavaScript: Deno, isolated-vm. Rust/Node/CLI 호스트에 적합한 V8 기반 런타임으로 세밀한 권한 제어가 가능하고 모든 권한을 끌 수 있다.
- Python: Monty(실험적). AI 용도로 만든 최소 파이썬 인터프리터로 기본적으로 입출력이 없다.
- TypeScript: pctx(초기 단계). 코드 모드 개념을 라이브러리로 제공하며 Rust 저수준 지원을 포함한다.
- 언어 무관(Wasm 경유): Wasmtime. 어떤 언어든 Wasm으로 컴파일해 역량 기반 보안으로 실행한다.

샌드박스와 무관하게 통합 패턴은 같다. 호스트가 함수 스텁을 주입하고, 프로세스 내부나 stdio 채널로 호출을 가로채며(네트워크 권한은 완전히 거부 가능), 이를 tools/call 요청으로 MCP 서버에 전달한다.

12. 실행 구조

샌드박스는 네트워크 접근 없이 모델 생성 코드를 실행하고, 외부와의 유일한 통로는 호스트로 호출을 되돌리는 함수 스텁이다. 호스트는 브로커 역할로 샌드박스의 호출을 받아 올바른 MCP 서버로 매핑해 실행하고 결과를 돌려준다. 인증 토큰과 자격 증명은 호스트가 보관하며 생성 코드에 노출되지 않는다. 모델은 샌드박스가 돌려주는 것, 보통 console.log 출력이나 최종 반환값만 본다.

13. 보안 고려 사항

- 호출별 권한 부여: 브로커도 명세상 MCP 호스트다. 샌드박스에서 온 호출에도 직접 호출과 같은 사람 개입 확인 정책을 적용한다. 스크립트 승인이 실행 중 모든 도구 호출의 포괄 승인이 되어서는 안 되며, 범주형 승인(예: 이 스크립트 실행 동안 ticketing_createIssue 허용)을 쓰더라도 브로커는 매 호출을 그 승인과 대조해야 한다.
- 서버 간 데이터 흐름: 한 서버의 도구 결과는 다른 서버에 대한 신뢰할 수 없는 입력이다. 브로커는 중개 호출에도 직접 호출과 같은 입력 검토 정책을 적용해야 하며, 출력 잘라내기만으로는 유출을 막지 못한다.
- 네트워크 격리: 샌드박스는 직접 네트워크에 접근하지 않아야 하고 모든 외부 통신은 권한과 접근 제어를 강제하는 호스트 브로커를 거친다.
- 자격 증명 비노출: API 키와 토큰은 호스트가 보관하고, 생성 코드는 타입 함수를 호출하며 호스트가 서버로 전달할 때 인증을 붙인다.
- 자원 제한: 폭주 스크립트를 막도록 실행 시간과 메모리 한도를 둔다.
- 출력 필터링: 샌드박스 콘솔 출력을 모델에 돌려주기 전에 검증하고 잘라낸다.

14. 오류 처리

MCP 도구 오류는 전송 실패가 아니라 isError: true가 담긴 성공 응답으로 온다. 생성 래퍼는 이를 예외로 바꿔 모델 작성 코드가 try/catch를 쓸 수 있게 해야 한다. 잡히지 않은 오류로 스크립트가 끝나면 그 오류를 스크립트 결과로 노출해 모델이 스스로 고칠 수 있게 하고, 이미 반영된 부분 부작용을 보고하는 책임은 모델에 둔다.

15. 두 패턴의 결합

점진적 발견과 프로그래밍 방식 도구 호출은 함께 쓸 때 효과적이다. 모델이 발견 도구로 필요한 도구를 찾아 스키마를 불러온 뒤, 여러 도구를 한 번에 호출하는 스크립트 하나를 작성하면 도구 정의의 토큰 비용과 도구 결과의 토큰 비용을 모두 줄이고 모델 컨텍스트를 데이터 전달이 아닌 추론에 집중시킬 수 있다.

여러분의 MCP 호스트에서는 도구 정의가 컨텍스트에서 어느 정도 비중을 차지할 때 점진적 발견으로 전환하는지, 코드 모드를 도입했다면 샌드박스 격리를 어떻게 구성했는지 댓글로 경험을 나눠 주세요.

---
출처: Model Context Protocol 문서 「클라이언트 모범 사례」 (Model Context Protocol 기여자)
https://modelcontextprotocol.io/docs/develop/clients/client-best-practices
라이선스: CC BY 4.0 https://creativecommons.org/licenses/by/4.0/deed.ko
변경 사항: 리퀘오 운영팀이 2026-11-10에 한국어로 번역하고 일부 축약·재구성했습니다. 원문 작성자가 이 번역을 보증하지 않습니다.

로그인하면 누를 수 있습니다. 로그인하면 저장하고 새 답글 알림을 받을 수 있습니다.

AI 차트 도구 (AI 요약·회원 리뷰·인기점수)

답글 0

아직 답글이 없습니다.