MCP 서버가 에이전트의 컨텍스트 창을 낭비하는 방법

훌륭한 MCP 서버를 구축했습니다. 이 서버는 상세 스키마를 가진 42개의 도구를 나열하며, 이제 에이전트는 내부 API, 데이터베이스, 배포 파이프라인에 대한 완전한 접근 권한을 갖게 되었습니다.

3주 후, 에이전트가 이전 지침을 잊어버리고, 도구 이름을 환각(hallucinating)처럼 만들고, 작업을 진행하는 중간쯤에서 토큰 제한에 부딪히는 것을 발견합니다. 당신은 모델 자체가 충분히 똑똑하지 않다고 생각하고 모델을 바꿉니다. 하지만 문제는 약간 더 심해집니다.

문제는 모델이 아닙니다. MCP 서버가 에이전트의 컨텍스트 창을 쓰레기통처럼 사용하고 있다는 것입니다.

즉시 로드 비용 (The eager-load tax)

대부분의 MCP 서버는 세션 시작 시 모든 도구를 노출합니다. 모델은 코드베이스의 첫 줄을 읽기도 전에 전체 도구 카탈로그, 모든 설명, 모든 매개변수 스키마 및 리소스 목록을 받게 됩니다. 20만 토큰 컨텍스트 창에서, 30개의 엔드포인트를 가진 잘 구축된 내부 API는 에이전트가 아무것도 하지 않았음에도 불구하고 예산의 8~15%를 소모할 수 있습니다.

에이전트는 30개의 도구가 필요하지 않습니다. 단 2개만 필요합니다. 하나는 편집하려는 파일을 읽고, 다른 하나는 방금 작성한 테스트를 실행하는 도구입니다. 나머지 28개는 실제 작업을 방해하는 불필요한 무게(dead weight)일 뿐입니다.

실제로 도움이 되는 것들

리소스별이 아닌 기능별로 분할하세요. 모든 것을 아는 하나의 거대한 서버를 배포하지 마십시오. 좁은 범위의 서버들을 만드세요: 파일 작업을 위한 하나, 테스트하는 API를 위한 하나, 배포를 위한 하나와 같이요. 에이전트는 현재 작업에 필요한 것만 로드합니다. 6개 도구짜리 서버는 42개 도구짜리 서버보다 훨씬 적은 비용이 들고, 에이전트가 그 좁은 범위의 작업에서 성공률이 높아집니다. 왜냐하면 비슷한 이름의 도구들 사이에서 선택할 필요가 없기 때문입니다.

긴 페이로드 대신 짧은 오류를 반환하세요. 도구가 실패했을 때, 에이전트는 오류를 읽고 재시도합니다. 400줄짜리 스택 트레이스는 쓸모없을 때보다 더 나쁩니다. 컨텍스트 창을 범람시키고, 모델은 그것을 절반만 읽으며, 같은 잘못된 가정으로 재시도하게 만듭니다. 오류 코드 2줄, 로그를 가리키는 포인터, 그리고 어떤 매개변수가 잘못되었는지에 대한 힌트를 반환하세요. 에이전트가 필요하면 더 자세한 내용을 요청할 수 있습니다.

스키마가 필터링을 하도록 만드세요. 도구 설명(Tool descriptions)은 모델에게 이 도구를 언제 호출하지 말아야 하는지 알려주어야 합니다. "생산 환경 배포에서만 사용하고, 스테이징 환경에서는 절대 사용하지 마십시오." 또는 "레거시 버전을 선호합니다"와 같은 방식으로 지침을 제공하는 것입니다. 모델은 이러한 모호성 해소 장치(disambiguators)를 사용하여 올바른 도구를 선택하며, 잘 좁혀진 스키마는 잘못된 호출과 재시도 횟수를 줄여줍니다.

도구에 버전을 부여하고 명확하게 사용 중단하세요. 동일한 엔드포인트의 v1과 v2가 있다면, 설명에서 v1을 사용 중단(deprecated)으로 표시하십시오. 에이전트들은 여전히 이를 호출할 것이지만 빈도가 줄어들고, 텔레메트리(telemetry)를 통해 호출이 0건임을 확인하면 제거할 수 있습니다. "혹시 몰라서" 둘 다 살아있게 두는 것이 결국 42개의 도구를 갖게 되는 원인입니다.

스펙이 지름길이다 (The spec is the shortcut)

저를 놀라게 한 부분은 이것입니다. 가장 효과적인 방법은 MCP 서버를 직접 작성하는 것이 아니라 OpenAPI 스펙(spec)으로부터 생성하는 것입니다. 스펙 기반 생성기(spec-driven generator)는 간결하고 일관된 도구 목록을 만듭니다. 즉, 작업당 하나의 도구, 예측 가능한 매개변수 이름, 발명된 헬퍼 없음, 중복 엔드포인트가 없습니다. 필요한 경로로만 스펙을 가지치기할 수 있으며, 서버도 그에 맞춰 조정됩니다.

이것은 우리가 Powerduck을 구축하는 동안 계속 직면했던 정확한 문제입니다. 우리는 로컬 우선(local-first) OpenAPI 에디터가 사용자가 현재 신경 쓰는 경로들로부터 최소한의 MCP 서버를 생성하는 역할을 하기를 원했습니다. 이 과정에서 에이전트가 결코 건드리지 않을 80개의 엔드포인트를 헤쳐나갈 필요가 없도록 말입니다. 스펙은 진실의 출처(source of truth)로 유지되고, 생성된 서버는 작게 유지되며, 에이전트는 실제 문제 해결에 필요한 컨텍스트 창(context window)을 확보할 수 있습니다.

지루한 테스트 (The boring test)

다음 MCP 서버를 배포하기 전에 한 가지를 해보십시오. 새로운 에이전트 세션을 열고 도구 카탈로그만으로 얼마나 많은 토큰을 소비하는지 계산해 보세요. 만약 3개의 도구가 필요한 작업에 대해 이 비용이 컨텍스트 창의 5%를 초과한다면, 잘못하고 있는 것입니다. 서버 범위를 좁히고, 오류 메시지를 간결하게 만들어서 모델이 메뉴를 읽는 대신 실제 작업에 집중하도록 하십시오.