Optimize
이 문서를 끝내면 MCP의 도구 정의를 뜻을 바꾸지 않고 줄인 오버레이를 만들고, 그 오버레이를 서빙하는 프록시를 MCP 클라이언트에 꽂는 절차를 아는 상태가 된다. 서버 코드는 건드리지 않는다.
두 명령
먼저 오버레이를 만들고, 그 오버레이를 프록시가 서빙한다.
# 1. 서버의 tools/list 를 읽어 오버레이를 만든다. 리포트가 stdout 에 나온다.
mcpeak optimize --out ./server.optimize.json -- node ./server.mjs
# 2. MCP 클라이언트 설정에서 서버 명령 자리에 프록시를 넣는다.
mcpeak-optimize-proxy ./server.optimize.json -- node ./server.mjs
mcpeak-optimize-proxy ./server.optimize.json --url http://localhost:3000/mcp--out 은 필수다. 서버 이름으로 파일명을 지어 주지 않는다. 서버 지정 방법은 test 와 같다.
바뀌는 것은 LLM 에게 보이는 tools/list 뿐이다. tools/call 은 원본 이름과 인자로 서버에 그대로 전달된다. 프록시는 시작할 때 원본 서버의 도구 이름 목록을 오버레이와 대조하고, 서버가 바뀌어 있으면 서비스하지 않고 오버레이를 다시 만들라고 안내한다.
리포트 읽기
examples/live-weather-server 에 돌리면 이렇게 나온다.
mcpeak optimize 결과
서버 도구 10개, instructions 없음
크기 (UTF-8 바이트, 토큰은 바이트÷4 근사)
원본 4443 (~1111 토큰)
압축 3923 (~981 토큰, 11.7% 감소)
instructions 증가분 0 (공통 파라미터 0개를 사전으로 옮김)
변환별 기여
무손실 정규화 -520 바이트
잡음 제거 -0 바이트
공통 파라미터 승격 -0 바이트 (사전 +0 포함)
가장 많이 줄어든 도구
get_forecast 337 → 285 (15.4%)
convert_currency 508 → 456 (10.2%)
이 오버레이는 tools/list 만 바꿉니다. tools/call 은 원본 이름과 인자로 서버에 전달됩니다.토큰 수는 UTF-8 바이트 ÷ 4 근사치다. 절감률은 서버가 정하고, 이 도구가 보장하는 것은 기능 유지다. --json 을 붙이면 리포트 대신 오버레이 JSON 이 stdout 에 나간다.
무엇을 바꾸나
공개 서버 35개, 모델 선택 테스트 210건, 스키마 동치 표본 약 72,000개에서 도구 선택을 바꾸지 않은 변환만 쓴다. 기대 감소는 서버별 중앙값 12%, 범위 1~38% 다.
| 변환 | 건드리는 것 | 왜 안전한가 |
|---|---|---|
| 무손실 정규화 | inputSchema 의 $schema·$id·$comment·title, additionalProperties:true, 빈 required·properties | 검증 의미가 바뀌지 않는다 |
| 잡음 제거 | 설명의 URL, Example: 이하 블록, 파라미터 이름을 되풀이하는 3단어 이하 설명 | 모델이 도구를 고르거나 인자를 채우는 데 쓰지 않는 정보다 |
| 공통 파라미터 승격 | 이름·설명이 같은 파라미터가 3개 이상 도구에 반복되면 설명을 서버 instructions 사전으로 한 번만 | 정보가 사라지지 않고 자리만 옮긴다 |
변환기는 자기 출력을 게이트(원본과 결과의 구조 동치 검사)에 통과시킨 뒤에만 오버레이를 쓴다. 통과하지 못하면 그것은 이 도구의 결함이며 문장이 그렇게 말한다.
하지 않는 것
- 파라미터 설명 삭제,
default삭제,additionalProperties:false삭제. 실측에서 오선택과 인자 누락을 냈다. - 도구 제외, 병합, 이름 변경. 호출 계약이 바뀐다.
- resources·prompts 중계. 프록시는 tools 만 광고한다. 원본이 다른 능력을 갖고 있으면 리포트가 경고한다.
주의
공통 파라미터 승격은 클라이언트가 서버 instructions 를 모델에게 보여 줄 때만 정보가 보존된다. instructions 를 무시하는 클라이언트에서는 그 파라미터 설명이 모델에 닿지 않는다. 그런 클라이언트가 대상이면 오버레이를 만들기 전에 이 점을 감안한다.
대시보드에서
대시보드의 분석 화면 토큰 탭이 같은 변환을 돌려 리포트를 보여 준다. 화면은 오버레이를 파일로 저장하지 않으므로 프록시에 꽂을 파일은 CLI 로 만든다.