SuperCompress MCP Server: Compress Context from Any MCP-Compatible AI Agent

AI agents are only as good as the context they can see. But long context costs money, consumes window space, and slows down inference. The SuperCompress MCP server lets any MCP-compatible agent — Claude Desktop, Claude Code, Cursor, Windsurf — compress context before sending it to an LLM, without leaving the agent workflow.

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI agents communicate with external tools and data sources. An MCP server exposes tools — like compress or retrieve — that the agent can invoke autonomously during a conversation.

The SuperCompress MCP server exposes three tools:

Tool	What it does
`compress`	Compresses a long context text. Supports compiler mode (max savings) and CCR mode (reversible with retrieval markers). Returns compressed text + token stats
`retrieve`	Retrieves original text by hash from a `[SC-Retrieve: hash]` marker. Checks in-memory cache first, then falls back to the hosted API if configured
`simple_hash`	Computes the content-addressed hash for any text. Useful for checking cache state before compressing

Why Run Compression as MCP?

Running compression through MCP means the agent handles context reduction automatically, without you switching tools or writing glue code:

No API key needed — The MCP server runs locally using the same compression engine as the hosted API. All processing happens on your machine.
Zero configuration — Point your MCP client at node /path/to/mcp/server.js and the tools appear immediately.
Agent-native — The agent decides when to compress, when to retrieve, and how to use the compressed context. You don't need to tell it what to do.
CCR works seamlessly — Compress with mode="ccr", get retrieval markers in the output, retrieve blocks as needed — all within the same conversation.

Setup

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "supercompress": {
      "command": "node",
      "args": ["/absolute/path/to/supercompress/mcp/server.js"]
    }
  }
}

Restart Claude Desktop. The compress, retrieve, and simple_hash tools appear in the available tools list automatically.

Claude Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "supercompress": {
      "command": "node",
      "args": ["/absolute/path/to/supercompress/mcp/server.js"]
    }
  }
}

Cursor

Add in Cursor Settings → MCP Servers:

Name: supercompress
Type: command
Command: node /absolute/path/to/supercompress/mcp/server.js

How the Agent Uses It

The agent calls the compress tool whenever it encounters context that's too large to fit in its window. Here's what happens:

Agent detects oversized context — Log files, codebase excerpts, conversation history, or API responses that exceed comfortable window size.
Agent calls compress — Passes the raw context and the current question. The MCP server runs the full SuperCompress engine (same as the hosted API) and returns compressed text with token savings stats.
Agent reads the compressed output — Proceeds with a smaller, query-relevant context. Token savings, important_kept_pct, and compression_risk are available in the second content block.
If CCR mode was used — The agent can later call retrieve with a hash from a [SC-Retrieve: hash] marker to get the original text for any dropped block.

Example conversation

User: Analyze this 10K-line log file for the root cause of the outage.
      [pastes log file]

Agent: [calls compress tool with context=log, query="root cause of outage"]
       [receives 120-line compressed output with 92% token savings]

Agent: Based on the compressed log, the root cause is...
       [provides analysis from the compressed content]

User: Show me the actual error messages around that timestamp.

Agent: [calls retrieve with hash from [SC-Retrieve: hash] marker]
       [retrieves original error block from cache]

Agent: Here are the exact error messages from the log...

Architecture

The MCP server reuses the same api/_lib/engine.js module as the Vercel-hosted API. This means:

The same compression model (loaded from web/assets/data/model.json)
The same domain preprocessors (JSON, Code, Log)
The same CCR logic (in-memory LRU cache, block-level markers)
The same simpleHash function for content-addressed addressing

The in-memory CCR cache persists across tool calls within a single MCP session. This means compress → retrieve flows work seamlessly as long as the MCP server process stays alive.

Hosted API Fallback for Retrieval

If you set the SUPERCOMPRESS_API_KEY environment variable, the retrieve tool falls back to the hosted API when content isn't found in the local in-memory cache. This is useful for retrieving content that was compressed and persisted by the hosted API in a previous session:

SUPERCOMPRESS_API_KEY=sc_live_YOUR_KEY node mcp/server.js

What's Next

The MCP server is available now in the SuperCompress repository. Future versions will add:

Anthropic cache_control middleware — Auto-wrapping compressed outputs with proper cache_control markers for Claude
Binary content support — Compress images and structured data alongside text context
Streaming compression — Progressive compression for real-time agent contexts