도구 38개, 컨텍스트는 아껴 쓰기: KwaFlux MCP 서버 설계기

핵심 요약

• MCP 서버가 제공하는 도구는 하나하나 모델에게 설명되고, 그 설명은 모델이 사용자의 요청에 쓸 수 있었던 컨텍스트를 차지합니다.
• 도구 38개를 모두 불러오면 KwaFlux의 도구 목록은 51,004바이트로, 60,000바이트 예산 안에 들어갑니다. 코어 그룹만 불러오면 7,077바이트로 줄어듭니다.
• 도구 그룹을 쓰면 실제로 쓰는 것만 불러올 수 있습니다. KWAFLUX_MCP_TOOLSETS를 설정하면 선택하지 않은 그룹은 모델에 전달되지 않습니다.
• 예산은 테스트로 검사합니다. 변경 사항 때문에 도구 목록, 코어 그룹, 서버 지침 중 하나라도 예산을 넘으면 테스트가 실패합니다.

기능이 많은 MCP 서버에는 눈에 잘 띄지 않는 비용이 있습니다. 모델이 도구가 있다는 것을 알 수 있도록 도구마다 이름, 설명, 입력 스키마가 모델에 전달된다는 점입니다. 도구가 몇 개뿐이라면 별문제가 없습니다. 하지만 38개라면 사용자가 아무것도 입력하기 전부터 컨텍스트 윈도우의 적지 않은 몫을 차지할 수 있습니다.

KwaFlux의 MCP 서버는 이 비용을 중심에 두고 설계했습니다. 스키마는 손으로 쓰지 않고 생성합니다. 도구는 끌 수 있는 그룹으로 묶여 있습니다. 결과는 장황한 문장 대신 구조화된 데이터로 돌려줍니다. 그리고 크기마다 예산을 두고 테스트로 지킵니다.

이 글에서는 MCP 서버의 컨텍스트 비용이 어디서 생기는지, KwaFlux가 이를 어떻게 측정하고 제한하는지, 도구를 적게 불러오는 방법, 그리고 오래 걸리는 영상 작업을 적은 비용으로 지켜볼 수 있게 한 설계 선택을 알아봅니다.

목차

1. MCP 도구는 컨텍스트를 얼마나 쓸까요?
2. KwaFlux의 수치
3. 테스트로 지키는 예산
4. 쓰는 그룹만 불러오기
5. 앱 구성에서 생성하는 스키마
6. 두 번 읽을 필요 없는 결과
7. 오래 걸리는 작업: 폴링 대신 진행 알림과 취소
8. 여러 단계 워크플로를 위한 프롬프트
9. 자주 묻는 질문

MCP 도구는 컨텍스트를 얼마나 쓸까요?

MCP 도구의 컨텍스트 비용은 도구 정의의 크기입니다. 정의에는 이름, 제목, 설명, 입력과 출력의 JSON Schema가 들어가며, 호스트는 세션 안의 모든 요청에 이 정의를 함께 담아 모델에 전달합니다.

호스트는 tools/list 요청으로 정의를 받아 옵니다. 대부분의 호스트는 모델이 도구를 고를 수 있도록 이 정의를 모델의 컨텍스트에 넣습니다. MCP 사양은 서버가 도구를 일정한 순서로 돌려주도록 요구하는데, 그 이유 중 하나로 "도구가 모델 컨텍스트에 포함될 때 LLM 프롬프트 캐시 적중률을 높여 준다"는 점을 듭니다. 도구 정의가 컨텍스트에 들어가는 일이 그만큼 흔하다는 뜻입니다.

KwaFlux의 수치

전체 목록은 JSON으로 약 51 KB입니다. 토큰으로 몇 개인지는 모델의 토크나이저에 따라 다르지만, 첫 요청 전에 세션마다 한 번씩 치르는 고정 비용입니다. 코어 그룹만 불러오면 그 약 7분의 1입니다.

테스트로 지키는 예산

설계 문서에 적어 둔 크기 목표는 시간이 지나면 흐지부지됩니다. 테스트에 넣어 둔 크기 목표는 그렇지 않습니다.

KwaFlux의 MCP 서버에는 테스트의 일부로 실행되는 측정 스크립트가 있습니다. 실제 tools/list 응답을 만들어 바이트 단위로 재고, 코어 그룹만 따로 재고, 서버 지침은 글자 수로 잰 뒤, 하나라도 예산을 넘으면 실패 처리합니다.

이렇게 하면 도구를 쓰는 방식이 달라집니다. 새 도구도 예산 안에 들어가야 하므로 긴 설명은 다듬고, 되풀이되는 설명은 공용 지침으로 옮기고, 허용 값을 풀어 쓴 문단은 enum으로 바꿉니다. 앞으로 나올 기능을 위해 예산에는 여유를 조금 남겨 두었고, 전체 목록 기준으로 약 9 KB입니다.

쓰는 그룹만 불러오기

KwaFlux의 도구 38개는 여러 그룹으로 나뉘며, 주요 그룹은 아래 표에 정리했습니다. 코어 그룹은 어떤 구성에서든 불러옵니다. 나머지는 KWAFLUX_MCP_TOOLSETS 환경 변수로 고르며, 고르지 않은 그룹은 아예 등록되지 않으므로 컨텍스트를 전혀 쓰지 않습니다.

예를 들어 어시스턴트를 파일 변환과 복구에만 쓴다면, 호스트의 MCP 구성에서 KwaFlux 항목에 이 변수를 추가합니다.

{
  "mcpServers": {
    "kwaflux": {
      "command": "<path to node>",
      "args": ["<path to kwaflux_mcp.mjs>"],
      "env": { "KWAFLUX_MCP_TOOLSETS": "convert,repair" }
    }
  }
}

command와 args는 직접 입력하지 말고 KwaFlux의 설정 › Agent(MCP) 페이지에서 복사하세요. 위치는 빠른 시작 가이드에서 확인할 수 있습니다. 호스트마다 구성 형식이 다르므로 env는 사용하는 호스트가 요구하는 위치에 넣으세요.

팁: 어시스턴트로 무엇을 할 수 있는지 익히는 동안에는 전부 불러온 상태로 시작하고, 그다음 실제로 쓰는 그룹만 남기세요. 도구 목록이 작아지면 모델이 의도하지 않은 도구를 고를 가능성도 줄어듭니다.

앱 구성에서 생성하는 스키마

도구 목록에서 바이트를 가장 많이 차지하는 것은 입력 스키마입니다. 손으로 쓴 스키마는 점점 불어나기 쉽습니다. 필드를 문장으로 설명하고, 허용 값을 설명에 한 번, 스키마에 또 한 번 적고, 예외 사항을 덧붙이기 때문입니다.

KwaFlux의 향상 도구 스키마는 앱 화면과 같은 구성 파일에서 생성됩니다. 설정 하나하나가 실제 범위나 실제 선택지 목록을 가진, 형식이 정해진 필드가 되므로, 모델은 어떤 값이 허용되는지 설명하는 문장 대신 "enum": [...]을 보게 됩니다. 사진용 변형도 같은 파일에서 만들어집니다. 생성된 규칙이 불일치 테스트로 앱과 어긋나지 않게 유지되는 방식은 컨트롤 플레인 글에서 설명합니다.

이렇게 하면 도구의 범위도 좁게 유지됩니다. 도구마다 사람이 고를 만한 몇 개의 필드만 받고, 전체 작업은 KwaFlux가 직접 구성합니다. 날것의 작업 명세를 그대로 받는 도구라면 엔진이 할 수 있는 모든 것에 대한 스키마가 필요해지고, 그만큼 더 커지고 검사하기도 어려워집니다.

두 번 읽을 필요 없는 결과

KwaFlux의 모든 도구는 outputSchema를 선언합니다. MCP 사양에 따르면 도구가 이를 제공하는 경우 "서버는 이 스키마를 따르는 구조화된 결과를 제공해야 한다(MUST)"고, 클라이언트는 "구조화된 결과를 이 스키마에 맞춰 검증하는 것이 바람직하다(SHOULD)"고 합니다.

컨텍스트 측면에서 이는 결과가 작업 ID, 상태, 출력 파일 이름처럼 예측 가능한 필드를 가진 간결한 JSON이라는 뜻입니다. 모델은 작업이 성공했는지 알아내려고 문단을 읽을 필요가 없고, 호스트는 모델에 묻지 않고도 결과를 확인할 수 있습니다. 결과에는 모델에 필요 없는 정보도 빠져 있는데, 이 내용은 경로와 개인정보 글에서 다룹니다.

오래 걸리는 작업: 폴링 대신 진행 알림과 취소

영상 작업은 몇 분씩 걸릴 수 있습니다. 어시스턴트가 작업을 지켜보는 가장 단순한 방법은 "끝났어?"라고 계속 묻는 것인데, 확인할 때마다 컨텍스트가 늘어납니다.

KwaFlux의 코어 그룹에는 그 대신 대기 도구가 있습니다.

• 진행 상황. 호스트가 progressToken을 넣어 보내면 KwaFlux는 작업이 진행되는 동안 notifications/progress를 보냅니다. 호스트는 이를 모델의 컨텍스트 밖에서 진행률 표시줄로 보여 줍니다.
• 취소. 호스트에서 요청을 중지하면 notifications/cancelled가 전송되고, KwaFlux는 곧바로 대기를 멈춥니다. 원한다면 그다음 어시스턴트가 작업 자체를 취소할 수 있습니다.

대기 호출 한 번이 상태 확인 반복을 대신하므로, 10분짜리 내보내기도 10초짜리와 거의 같은 컨텍스트만 씁니다.

여러 단계 워크플로를 위한 프롬프트

진단, 복구, 향상, 내보내기처럼 여러 도구를 차례로 써야 하는 작업도 있습니다. 이 순서를 도구마다 설명에 적으면 요청할 때마다 바이트가 듭니다. 그래서 KwaFlux는 이를 MCP 프롬프트 4개로 제공합니다.

• 손상된 영상 복구
• 플랫폼에 맞춰 내보내기
• 다운로드 후 변환
• AI 화질 복구

MCP 사양은 프롬프트를 "사용자가 제어하는(user-controlled)" 것으로 설명하며, 보통 슬래시 명령으로 노출됩니다. 고르기 전까지는 비용이 들지 않고, 고르면 해당 작업의 단계를 모델에 알려 줍니다. 각 단계가 무엇을 하는지는 기능 소개 글에서 볼 수 있습니다.

마치며

도구 목록을 카탈로그가 아니라 예산으로 다루세요. 크기를 재고, 테스트로 상한을 걸고, 필요한 그룹만 불러올 수 있게 하세요. 그런 다음 실제 구성에서 생성한, 형식이 정해진 입력, 구조화된 결과, 폴링 대신 진행 알림으로 호출 하나하나의 비용을 낮게 유지하세요. KwaFlux는 이렇게 해서 서버 하나에 도구 38개를 담으면서도 사용자의 요청이 밀려나지 않게 합니다.

필요한 도구만 불러오고 나머지는 빼세요

KwaFlux의 로컬 MCP 서버는 Codex, Claude, Cursor 등 MCP 앱에 그룹 단위로 켜고 끌 수 있는 최대 38개의 도구를 제공하며, 코어 그룹은 모든 구성에서 켜져 있습니다. AI 처리는 사용자 GPU에서 실행되며 미디어 파일이 처리를 위해 업로드되지 않습니다. Windows 10(64비트, 버전 1809 이상), Windows 11, Apple Silicon 탑재 macOS 12 이상에서 실행됩니다. 파일 가져오기와 앱 둘러보기에는 계정이 필요 없습니다. 내보내기, 변환, 파일 복구, 링크에서 파일 다운로드에만 로그인과 유료 플랜이 필요합니다.

KwaFlux 받기 · 플랜 보기