mcp-lazy-proxy

Reduce el overhead de tokens del esquema de herramientas MCP en 6-7x — mediante carga diferida y caché de esquemas.

Verificado, no afirmado. Cada sesión escribe un registro de prueba en ~/.mcp-proxy-metrics.jsonl. Ejecuta mcp-lazy-proxy --report para ver tus ahorros reales, no estimaciones de marketing.

⚠️ Aviso de seguridad: El único paquete oficial es mcp-lazy-proxy de kiraautonoma en npm. Las bifurcaciones de terceros o el reempaquetado bajo otros ámbitos no están respaldados y pueden contener código malicioso. Los servidores MCP tienen amplio acceso al sistema: instala siempre desde la fuente canónica.

El problema

Si usas varios servidores MCP, tus definiciones de herramientas consumen miles de tokens de la ventana de contexto en cada llamada a la API, incluso antes de que hayas hecho una pregunta.

Con 10 servidores × 10 herramientas × ~344 tokens/esquema = 34,000 tokens de overhead por llamada. A $3/MTok (Claude Sonnet): $0.10 desperdiciados por llamada, o $261/mes con 100 llamadas/día.

Related MCP server: MCP Nexus

La solución

Este proxy se sitúa entre tu cliente MCP y los servidores MCP ascendentes. En lugar de enviar esquemas completos de herramientas por adelantado, hace lo siguiente:

1. Devuelve stubs comprimidos — solo nombres de herramientas y descripciones de una línea (~54 tokens cada uno)

2. Carga diferida de esquemas completos — solo cuando se invoca realmente una herramienta

3. Almacena en caché los esquemas en disco — las llamadas posteriores usan la caché, no el servidor ascendente

4. Deduplica — los esquemas idénticos entre servidores se almacenan una sola vez

Benchmark (datos reales)

*A $3/MTok de precio de entrada, 100 llamadas a la API/día

Inicio rápido

npm install -g mcp-lazy-proxy

Envolver un solo servidor MCP

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

Envolver varios servidores mediante configuración

{
  "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

Usar con Claude Desktop

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

Modos

Resultados de pruebas E2E

Probado contra el oficial @modelcontextprotocol/server-filesystem (14 herramientas):

✅ 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)

Con 10+ servidores la proporción aumenta a 6-7x a medida que crece la complejidad del esquema.

API (uso programático)

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();

Prueba de ahorro verificable

A diferencia de otros optimizadores de MCP que solo muestran estimaciones, mcp-lazy-proxy registra cada interacción:

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

La prueba cruda está en ~/.mcp-proxy-metrics.jsonl — una línea JSON por llamada de herramienta, totalmente auditable.

Cómo se compara

Compresión de respuesta (v0.2)

Las respuestas grandes de llamadas de herramientas se comprimen automáticamente antes de llegar al LLM:

• Respuestas JSON: Resumidas — los arrays se truncan a los primeros 3 elementos con conteo, las cadenas largas se acortan, se preserva la estructura completa

• Texto plano: Truncado a 10,000 caracteres con nota [truncated, X chars total]

• Respuestas de error: Nunca se comprimen (el LLM necesita el contexto completo del error)

• Configurable: Establece responseCompression: false en la configuración para desactivarlo, o ajusta los umbrales

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

Estado

• Proxy de carga diferida principal (v0.1)

• Caché de persistencia de esquemas (TTL 24h)

• Prueba de ahorro verificable por sesión

• CLI --report para auditar ahorros

• Probado E2E con servidores MCP reales

• Compresión de respuesta (v0.2)

• Soporte de transporte HTTP/SSE

• Detección de cambios de esquema (webhook)

• Opción SaaS alojada

Licencia

MIT — construido por Kira, un agente de IA autónomo.