Zero Trust Notice: Este artículo sigue la metodología de investigación zero-trust. Los datos marcados como “VERIFICADO” tienen evidencia fresca. Los datos marcados como “NO VERIFICADO” solo aparecen en el artículo introductorio y NO se encontraron en fuentes primarias.

mcp-compressor es el proyecto de Atlassian Labs para comprimir tool definitions de MCP servers. Con 66 estrellas y backing oficial de Atlassian, promete reducir el consumo de tokens por herramientas.

Pero hay un problema: los números 70-97% NO están respaldados por benchmarks verificables.

1. Introducción — Qué es y quién lo mantiene

El mantenedor

Atlassian Labs — El equipo de desarrollo interno de Atlassian.

• Creador de productos como Jira, Confluence, Bitbucket
• Publica proyectos open source en atlassian-labs/
• Tiene un blog oficial sobre MCP compression
• Publica benchmarks de 70-97% ahorro en tool definitions

El proyecto

Repositorio

GitHub: https://github.com/atlassian-labs/mcp-compressor
Blog oficial: https://www.atlassian.com/blog/development/mcp-compression-preventing-tool-bloat-in-ai-agents/
Docs: https://atlassian-labs.github.io/mcp-compressor/

El enigma de los benchmarks

2. Arquitectura — Cómo funciona internamente

Diagrama de flujo

┌─────────────────┐
│ MCP Client      │
│ (Claude Code)   │
└────────┬────────┘
         │ 1. tools/list
         ▼
┌─────────────────┐
│ mcp-compressor  │
│ (Proxy)         │
└────────┬────────┘
         │ 2. tools/list (backend)
         ▼
┌─────────────────┐
│ Backend MCP     │
│ Server          │
└────────┬────────┘
         │ 3. All tools + schemas
         ▼
┌─────────────────┐
│ mcp-compressor  │
│ (Compress)      │
└────────┬────────┘
         │ 4. Compressed wrappers
         ▼
┌─────────────────┐
│ MCP Client      │
│ (Solo wrappers) │
└─────────────────┘

Los 2 patrones

2.1 Compressed MCP proxy

El frontend expone wrappers en vez de tools completas:

server_get_tool_schema
server_invoke_tool
server_list_tools (solo a max compression)

Ventajas:

• El modelo ve una superficie pequeña primero
• Pide el schema completo solo para la tool seleccionada
• Luego invoca la tool

2.2 Local proxy for SDKs

La SDK inicia un proxy local para generated clients:

App (Python / TypeScript / Rust)
  ↓
CompressorClient
  ↓
Local session proxy (/token auth)
  ↓
Generated clients (CLI / Python / TS functions)
  ↓
Backend MCP servers

Ventajas:

• No necesitas spawnear mcp-compressor stdio subprocess
• Generated clients llaman al proxy con session token
• Puedes usar desde código o shell commands

3. Los 4 niveles de compresión

Ejemplos de compresión

Para una tool echo(message): Echo a message from alpha:

Nota: Solo low y medium mantienen descripciones. high y max pierden contexto.

4. Instalación paso a paso

Prerrequisitos

• Python 3.11+ (para Python SDK)
• Node.js 18+ (para TypeScript SDK)
• Rust 1.70+ (para Rust SDK)

Opción 1: CLI proxy

# Instalar
pip install mcp-compressor

# O con Rust (cargo)
cargo install mcp-compressor

# Usar
mcp-compressor -c medium -- python server.py

# O con remote HTTP MCP
mcp-compressor -c medium -- https://mcp.example.com/v1/mcp

Opción 2: Python SDK

from mcp_compressor import CompressorClient

with CompressorClient(
    servers={"local": {"command": "python", "args": ["server.py"]}},
    compression_level="medium",
) as proxy:
    print([tool.name for tool in proxy.tools])
    result = proxy.invoke("myTool", {"arg": "value"})
    print(result)

Opción 3: TypeScript SDK

import { CompressorClient } from "@atlassian/mcp-compressor";

const client = new CompressorClient({
  servers: { local: { command: "python", args: ["server.py"] } },
  compressionLevel: "medium",
});

const proxy = await client.connect();
try {
  console.log(proxy.tools.map((tool) => tool.name));
  console.log(await proxy.invoke("myTool", { arg: "value" }));
} finally {
  proxy.close();
}

Opción 4: Rust SDK

use mcp_compressor::compression::CompressionLevel;
use mcp_compressor::sdk::{CompressorClient, ServerConfig};
use serde_json::json;

let proxy = CompressorClient::builder()
    .server("local", ServerConfig::command("python").arg("server.py"))
    .compression_level(CompressionLevel::Medium)
    .build()
    .connect()
    .await?;

let result = proxy.invoke("myTool", json!({ "arg": "value" })).await?;

Verificación

# Ver tools comprimidos
mcp-compressor -c medium -- python server.py

# Deberías ver:
# - server_get_tool_schema
# - server_invoke_tool
# - server_list_tools (si compression=max)

5. Configuración — Config files y ejemplos

Config con tool filters

mcp-compressor -c medium \
  --server-name atlassian \
  --include-tools getAccessibleAtlassianResources,getConfluencePage \
  -- https://mcp.atlassian.com/v1/mcp

Config con OAuth

Para Atlassian MCP (OAuth-first):

# Primera run: abre browser para autorizar
mcp-compressor -c medium \
  --server-name atlassian \
  -- https://mcp.atlassian.com/v1/mcp

# Runs subsiguientes: reusa OAuth credentials

Config JSON avanzada

{
  "servers": {
    "alpha": {
      "command": "python",
      "args": ["server.py"],
      "env": {"API_KEY": "secret"}
    },
    "beta": {
      "url": "https://mcp.example.com/v1/mcp"
    }
  },
  "compression_level": "high",
  "server_name": "alpha",
  "include_tools": ["tool1", "tool2"]
}

6. Generated Clients

CLI Mode

Genera shell commands:

mcp-compressor --cli-mode \
  --server-name atlassian \
  -- https://mcp.atlassian.com/v1/mcp

# Generated command:
atlassian get-accessible-atlassian-resources

Code Mode

Genera Python o TypeScript functions:

# generated-py/atlassian.py
import atlassian

resources = atlassian.getAccessibleAtlassianResources()

import { getAccessibleAtlassianResources } from "./generated-ts/atlassian.ts";

const resources = await getAccessibleAtlassianResources();

Just Bash integration

Para comandos bash:

mcp-compressor -c medium \
  --just-bash \
  -- python server.py

# Then use:
atlassian echo --message hi

7. Pitfalls — Problemas comunes y soluciones

Pitfall 1: Compression level too high

Problema: high o max pierden descripciones de tools.

Solución:

# Use medium por defecto
mcp-compressor -c medium -- python server.py

# Solo use high/max si el modelo ya conoce las tools
mcp-compressor -c high -- python server.py

Pitfall 2: Tool filters too restrictive

Problema: --include-tools filtra tools necesarias.

Solución:

# Omita --include-tools para ver todas
mcp-compressor -c medium -- python server.py

# O use --exclude-tools para excluir específicas
mcp-compressor -c medium \
  --exclude-tools deprecated_tool,debug_tool \
  -- python server.py

Pitfall 3: OAuth credentials not reused

Problema: Cada run pide OAuth.

Solución:

# MCP-compressor guarda credenciales automáticamente
# Asegúrate de usar el mismo --server-name
mcp-compressor -c medium \
  --server-name atlassian \
  -- https://mcp.atlassian.com/v1/mcp

Pitfall 4: Generated clients out of sync

Problema: Backend tools cambiaron, generated clients no.

Solución:

# Regenerate clients
mcp-compressor --cli-mode \
  --server-name atlassian \
  -- https://mcp.atlassian.com/v1/mcp

# O use Code Mode para regenerar módulos

8. Benchmarks — ¿Qué sabemos y qué NO?

✅ Lo que SÍ sabemos (VERIFICADO)

❌ Lo que NO sabemos (NO VERIFICADO)

⚠️ Comparación con OneTool

Conclusión: Ambos proyectos hacen claims de ahorro sin benchmarks verificables en GitHub issues, PRs, o documentación oficial.

9. Casos de uso — Cuándo usarlo (y cuándo NO)

✅ Cuándo usar mcp-compressor

❌ Cuándo NO usar mcp-compressor

10. Comparación — vs otros proyectos

mcp-compressor vs context-mode

Veredicto: context-mode es más completo y con comunidad masiva. mcp-compressor es complementario para tool definitions.

mcp-compressor vs OneTool

Veredicto: OneTool tiene más tools pero GPL v3. mcp-compressor es más flexible pero requiere más setup.

mcp-compressor vs token-optimizer

Veredicto: token-optimizer es más maduro y con analytics. mcp-compressor es complementario para tool definitions.

11. Conclusión — Recomendación final

Resumen

mcp-compressor es el compresor de MCP de Atlassian Labs con backing oficial y 3 SDKs. Sin embargo:

• ⚠️ Los benchmarks 70-97% NO están verificados — Solo aparecen en el blog de Atlassian Labs
• ✅ Arquitectura sólida — 4 niveles de compresión, 2 patrones, generated clients
• ✅ 3 SDKs — Python, TypeScript, Rust
• ⚠️ Comunidad pequeña — 66 estrellas vs 16K de context-mode
• ⚠️ Sin session continuity — Complementario con context-mode

Cuándo usarlo

Use mcp-compressor si:

• Tienes múltiples MCP servers existentes
• Estás en un entorno enterprise con Atlassian stack
• Necesitas Python/TypeScript/Rust SDKs
• No te importa que los benchmarks NO estén verificados

Don’t use mcp-compressor si:

• Solo usas Hermes Agent
• Solo tienes 1-2 MCP servers
• Necesitas session continuity
• Prefieres proyectos con benchmarks verificables

Setup recomendado

# Para MCP servers existentes
mcp-compressor -c medium -- python server.py

# Para Atlassian MCP (OAuth)
mcp-compressor -c medium \
  --server-name atlassian \
  -- https://mcp.atlassian.com/v1/mcp

Combinación ganadora

Para maximum optimization:

Claude Code + mcp-compressor + context-mode

• mcp-compressor comprime tool definitions (70-97% NO verificado)
• context-mode comprime output (98% VERIFICADO)
• Ahorro total: ~90% en input + output (con la advertencia de que input side NO está verificado)

Next steps

Si quieres más detalles:

• Official docs
• GitHub repo
• Atlassian Blog — Fuente de los benchmarks NO verificados

📚 Recursos adicionales

Documentation

• mcp-compressor v0.1.0 docs
• Quickstart guide
• How compression works

Artículos relacionados

• MCP Token Optimization: 4 proyectos comparados — Artículo introductorio con la afirmación 70-97%
• Context-mode en profundidad — Artículo con benchmarks VERIFICADOS
• token-optimizer en profundidad — Próximo artículo
• OneTool en profundidad — Último artículo de la serie

GitHub

• mcp-compressor repository — 66 estrellas, 7 forks
• Issues list — 1 issue abierta

💭 ¿Qué te parece?

¿Has usado mcp-compressor? ¿Verificaste los benchmarks 70-97%? ¿Prefieres context-mode con benchmarks VERIFICADOS? ¿O ambos son complementarios? Déjame un comentario.