mcp-lazy-proxy

MCP 도구 스키마 토큰 오버헤드를 6-7배 절감 — 지연 로딩(lazy-loading) 및 스키마 캐싱을 통해.

검증된 수치, 단순 주장이 아닙니다. 모든 세션은 ~/.mcp-proxy-metrics.jsonl에 증명 로그를 기록합니다. mcp-lazy-proxy --report를 실행하면 마케팅 추정치가 아닌 실제 절감액을 확인할 수 있습니다.

⚠️ 보안 공지: 공식 패키지는 npm의 mcp-lazy-proxy(kiraautonoma 작성)뿐입니다. 다른 스코프로 배포된 서드파티 포크나 재패키징은 승인되지 않았으며 악성 코드를 포함할 수 있습니다. MCP 서버는 광범위한 시스템 접근 권한을 가지므로 — 반드시 공식 소스에서 설치하세요.

문제점

여러 MCP 서버를 사용하면 도구 정의가 모든 API 호출마다 수천 개의 토큰을 컨텍스트 창에서 소비합니다 — 질문을 던지기도 전에 말이죠.

서버 10개 × 도구 10개 × 스키마당 ~344토큰 = 호출당 34,000토큰 오버헤드. $3/MTok(Claude Sonnet) 기준: 호출당 $0.10 낭비, 하루 100회 호출 시 월 $261.

Related MCP server: MCP Nexus

해결책

이 프록시는 MCP 클라이언트와 업스트림 MCP 서버 사이에 위치합니다. 전체 도구 스키마를 미리 보내는 대신:

1. 압축된 스텁(stub)만 반환 — 도구 이름과 한 줄 설명만(~54토큰)

2. 전체 스키마는 지연 로딩 — 도구가 실제로 호출될 때만 로드

3. 스키마를 디스크에 캐싱 — 이후 호출은 업스트림 서버가 아닌 캐시를 사용

4. 중복 제거 — 동일한 스키마는 서버 간에 한 번만 저장

벤치마크(실제 데이터)

*$3/MTok 입력 가격 기준, 하루 100회 API 호출

빠른 시작

npm install -g mcp-lazy-proxy

단일 MCP 서버 래핑

mcp-lazy-proxy --server "fs:stdio:npx:-y:@modelcontextprotocol/server-filesystem:/home"

설정 파일로 여러 서버 래핑

{
  "servers": [
    {
      "id": "filesystem",
      "name": "Filesystem MCP",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home"]
    },
    {
      "id": "github",
      "name": "GitHub MCP",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  ],
  "mode": "lazy"
}

mcp-lazy-proxy --config proxy.json

Claude Desktop과 함께 사용

{
  "mcpServers": {
    "proxy": {
      "command": "mcp-lazy-proxy",
      "args": ["--config", "/path/to/proxy.json"]
    }
  }
}

모드

E2E 테스트 결과

공식 @modelcontextprotocol/server-filesystem(도구 14개)으로 테스트:

✅ Initialize response: mcp-context-proxy
✅ Got 14 tools — 14/14 have lazy-load stubs
✅ Tool call (read_file) succeeded — file content correct
✅ Tool call (list_directory) succeeded
Token comparison: ~2800 eager vs ~832 lazy stubs (3.4x on this small server)

서버가 10개 이상이 되면 스키마 복잡도가 증가함에 따라 절감 비율은 6-7배로 높아집니다.

API(프로그래매틱 사용)

import { MCPContextProxy } from 'mcp-lazy-proxy';

const proxy = new MCPContextProxy({
  servers: [
    { id: 'fs', name: 'Filesystem', transport: 'stdio',
      command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'] }
  ],
  mode: 'lazy'
});

await proxy.start();

검증 가능한 절감 증명

추정치만 보여주는 다른 MCP 최적화 도구와 달리, mcp-lazy-proxy는 모든 상호작용을 기록합니다:

# See your actual savings (not estimates)
mcp-lazy-proxy --report

원본 증명은 ~/.mcp-proxy-metrics.jsonl에 저장됩니다 — 도구 호출당 한 줄씩, 완전히 감사 가능합니다.

기능 비교

응답 압축(v0.2)

대용량 도구 호출 응답은 LLM에 도달하기 전에 자동으로 압축됩니다:

• JSON 응답: 요약 — 배열은 처음 3개 항목으로 잘라내고 개수 표시, 긴 문자열은 축약, 전체 구조는 유지

• 일반 텍스트: 10,000자로 잘라내고 [잘림, 총 X자] 메모 추가

• 오류 응답: 압축하지 않음(LLM이 전체 오류 컨텍스트를 필요로 함)

• 설정 가능: responseCompression: false로 비활성화하거나 임계값을 세밀하게 조정 가능

{
  "servers": [...],
  "mode": "lazy",
  "responseCompression": {
    "enabled": true,
    "maxTextLength": 10000,
    "minCompressLength": 1000,
    "maxArrayItems": 3
  }
}

상태

• 핵심 지연 로딩 프록시(v0.1)

• 스키마 영속 캐시(24시간 TTL)

• 세션별 절감액 검증 가능한 증명

• 절감액 감사용 --report CLI

• 실제 MCP 서버로 E2E 테스트 완료

• 응답 압축(v0.2)

• HTTP/SSE 전송 지원

• 스키마 변경 감지(웹훅)

• 호스팅 SaaS 옵션

라이선스

MIT — Kira가 개발한 자율 AI 에이전트가 제작.