---

📑 Table of Contents

• What is MCP Compression Proxy?
• ✨ Features
• 🚀 Quick Start
• 🎯 Usage
• ⌨️ mcp-cli (Progressive Tool Discovery)
• 🔧 Configuration
• 💡 Best Practices
• ❓ FAQ
• 🧪 Testing
• 🤝 Contributing
• 💖 Support This Project

---

What is MCP Compression Proxy?

A Model Context Protocol (MCP) server that solves two common problems:

1. Multi-server aggregation: Access tools from multiple MCP servers through a single connection
2. Context optimization: Reduce token consumption by 50-80% using intelligent LLM-based description compression

Instead of connecting to multiple MCP servers separately and consuming thousands of tokens on verbose tool descriptions, MCP Compression Proxy aggregates all your tools and compresses their descriptions intelligently—preserving critical information while removing redundancy.

Perfect for:

• Users with many MCP servers (filesystem, GitHub, databases, etc.)
• AI agents working with limited context windows
• Anyone wanting to minimize token costs while maximizing tool availability

✨ Features

• 🔗 Multi-Server Aggregation - Access tools from multiple MCP servers through one connection
• 🤖 LLM-Based Compression - Intelligent description compression (50-80% token reduction)
• 💾 Persistent Storage - Compressed descriptions saved to disk and restored on restart
• 🎭 Session-Based Expansion - Independent expansion state per conversation
• ⚡ Parallel Initialization - All servers connect in parallel with configurable timeouts
• 🎯 Selective Expansion - Compress all tools, expand only what you need
• 📦 Zero Config - Works out-of-the-box with sensible defaults
• 🔥 Standard MCP - Compatible with any MCP client (Claude Desktop, Cline, etc.)

🚀 Quick Start

Prerequisites

• Node.js 22+ installed on your system
• An MCP-compatible client (Claude Desktop, Cline, Continue.dev, etc.)

1. Install

Option A: Install from npm (recommended for most users):

npm install -g mcp-compression-proxy

Option B: Install from source (for development or latest features):

git clone https://github.com/kdpa-llc/mcp-compression-proxy.git
cd mcp-compression-proxy
npm install
npm run build

2. Configure MCP Client

Add to your MCP client configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

If installed via npm:

{
  "mcpServers": {
    "compression-proxy": {
      "command": "mcp-compression-proxy",
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

If installed from source:

{
  "mcpServers": {
    "compression-proxy": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-compression-proxy/dist/index.js"
      ],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

3. Configure Servers

Create a JSON configuration file to define which MCP servers to aggregate:

Option 1: User-level config (recommended for personal use)

• Location: ~/.mcp-compression-proxy/servers.json

Option 2: Project-level config (recommended for team projects)

• Location: ./servers.json (in the mcp-compression-proxy directory)

Example configuration:

{
  "mcpServers": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "enabled": true
    },
    {
      "name": "github",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      },
      "enabled": true
    }
  ]
}

Note: No rebuild needed! Just edit the JSON file and restart your MCP client.

4. Restart Your MCP Client

Restart your MCP client (e.g., Claude Desktop) to load the new configuration. The proxy will automatically connect to all configured MCP servers and make their tools available.

🎯 Usage

Tool Naming

Proxied tools from your configured MCP servers use the format serverName__toolName:

• filesystem__read_file
• filesystem__write_file
• github__create_issue

Management tools (built-in) don't have a prefix and are listed below.

Management Tools

Tool	Description
create_session	Create a new session for independent tool expansion
set_session	Set the active session
delete_session	Delete a session
clear_compressed_tools_cache	Clear all cached compressed tool descriptions
get_uncompressed_tools	Get tools that need compression (batch processing)
cache_compressed_tools	Save compressed descriptions to cache (batch processing)
compress_via_sampling	Compress automatically using the client's own LLM (requires sampling support)
expand_tool	Expand a tool to show full description (session-specific)
collapse_tool	Collapse tool back to compressed description
stats	Return JSON summary of coverage, cache health, sessions, and per-server tool counts

Use stats from your client (e.g., mcp-compression-proxy__stats) to sanity-check coverage. Optional inputs: serverName to scope to one backend and detailLevel (summary or full, default summary). The response includes coverage %, estimated token savings, cache state, active sessions, and per-server tool counts (respecting your exclude patterns).

Automatic Compression (MCP Sampling)

If your client supports MCP sampling, the proxy can compress
descriptions by borrowing the client's own LLM — no API key, no second model
to configure, and no work for you beyond one tool call:

mcp-compression-proxy__compress_via_sampling

It reads the uncompressed tools, asks the host to rewrite them, caches the
results, and reports before/after coverage. Call it again for the next batch
until nothing remains. Batches are sent one at a time, since a host may ask
you to approve each request.

Support varies by client — Cursor implements sampling; Claude Desktop and
Cline did not at the time of writing. On a client without it the tool returns
an error pointing at the manual get_uncompressed_tools →
cache_compressed_tools flow, which works everywhere.

Workflow Example

1. Before Compression

When you first ask your AI assistant about available tools:

User: What tools do you have?

AI: I have access to these tools:
- filesystem__read_file: Reads the complete contents of a file at the
  specified path. The file must exist and be readable. Returns the file
  contents as text. Supports absolute and relative paths. Maximum file
  size is 10MB. Will throw an error if the file doesn't exist...
  [~200 tokens for one tool]

2. Enable Compression (One-Time Setup)

Ask your AI assistant to compress the descriptions:

User: Use the mcp-compression-proxy tools to compress tool descriptions and save model context

AI: I'll compress the tool descriptions:
1. Getting all tools via get_uncompressed_tools...
2. Compressing descriptions intelligently...
3. Saving compressed versions via cache_compressed_tools...

Done! Tool descriptions are now compressed and saved to cache.

3. After Compression

The same request now uses far fewer tokens:

User: What tools do you have?

AI: I have access to these tools:
- filesystem__read_file: Read file contents (text, max 10MB)
- filesystem__write_file: Write/overwrite file
- github__create_issue: Create GitHub issue
  [~30 tokens for one tool]

Result: ~70% reduction in tokens for tool listings!

4. Persistent Storage

Compressed descriptions are automatically saved to disk at ~/.mcp-compression-proxy/cache.json and loaded on server restart. No need to re-compress after restarting!

To clear the cache if needed:

# If installed via npm
mcp-compression-proxy --clear-cache

# If installed from source
node dist/index.js --clear-cache

💡 Tip: After setting up, simply tell your AI: "Compress the tool descriptions to save context" and it will handle the rest!

⌨️ mcp-cli (Progressive Tool Discovery)

The package also installs mcp-cli, a second entry point for agents that
would rather shell out than hold every tool definition in context. Instead
of loading all tools up front, the agent lists or searches for what it needs
and pulls the full schema only for the tool it is about to call.

A background daemon keeps warm connections to the backend MCP servers, so
each command is a short IPC round-trip rather than a fresh server startup.

mcp-cli tools                          # List all tools (compressed)
mcp-cli search <query>                 # Search tools by name/description
mcp-cli info <server>/<tool>           # Full schema for one tool
mcp-cli call <server>/<tool> '<json>'  # Execute a tool
mcp-cli stats                          # Compression statistics

mcp-cli daemon start                   # Start the background daemon
mcp-cli daemon status                  # Show daemon status
mcp-cli daemon stop                    # Stop the daemon

The daemon starts automatically on first use. Pass --no-auto-start to fail
fast instead when it is not already running.

call also accepts its JSON argument on stdin, which avoids shell quoting
problems with large payloads:

echo '{"path": "/tmp/notes.md"}' | mcp-cli call filesystem/read_file

CLI Configuration

The optional cli block in servers.json tunes daemon behavior:

{
  "cli": {
    "payloadThreshold": 500,
    "autoStartDaemon": true,
    "daemonLogLevel": "info"
  },
  "mcpServers": []
}

Field	Type	Default	Description
payloadThreshold	number	500	Tool output longer than this many characters is written to a temp file and replaced with a reference, keeping large payloads out of the agent's context
autoStartDaemon	boolean	true	Start the daemon automatically when a command needs it
daemonLogLevel	string	"info"	Daemon log level (debug, info, warn, error)

Daemon state lives in ~/.mcp-compression-proxy/ (socket, PID file, and
daemon.log), created with 0700 permissions since the control socket
accepts commands that execute downstream MCP tools.

🔧 Configuration

Server Configuration

Create or edit your JSON configuration file at:

• ~/.mcp-compression-proxy/servers.json (user-level), or
• ./servers.json (project-level)

{
  "mcpServers": [
    {
      "name": "my-server",
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      },
      "enabled": true
    }
  ]
}

Configuration Schema

Root Level:

Field	Type	Required	Description
mcpServers	array	✅	Array of server configurations
excludeTools	string[]	❌	Tool name patterns to exclude from tool list entirely (supports wildcards)
noCompressTools	string[]	❌	Tool name patterns to never compress - descriptions pass through unchanged (supports wildcards)
defaultTimeout	number	❌	Default timeout in seconds for all servers (default: 30). Can be overridden per-server.
inheritEnv	boolean | string[]	❌	Which of the proxy's environment variables backend servers inherit (default: true). Can be overridden per-server.
compressionFallbackBehavior	"original" | "blank"	❌	What to show for a tool that has not been compressed yet (default: "original")

Server Configuration:

Field	Type	Required	Description
name	string	✅	Unique server identifier
command	string	✅	Command to execute
args	string[]	❌	Command arguments
env	object	❌	Environment variables
inheritEnv	boolean | string[]	❌	Overrides the root-level inheritEnv for this server
enabled	boolean	❌	Enable/disable server (default: true)
timeout	number	❌	Server-specific timeout in seconds (overrides defaultTimeout)

Environment Variable Expansion

Use ${VAR_NAME} syntax to reference environment variables:

{
  "mcpServers": [
    {
      "name": "github",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}",
        "GITHUB_ORG": "${MY_GITHUB_ORG}"
      }
    }
  ]
}

Variables are expanded at runtime from your shell environment.

Two extra forms are supported:

Syntax	Meaning
${VAR}	Substitutes VAR, or an empty string with a warning if it is not set
${VAR:-fallback}	Substitutes VAR, or fallback when unset or empty
$${VAR}	Escapes the expansion — produces the literal text ${VAR}

If a ${VAR} reference cannot be resolved, the proxy logs a warning naming
the variable. An unset variable becomes an empty string, which downstream
servers usually report as an authentication failure rather than a config
error, so check the startup log first when a server rejects valid-looking
credentials.

What Backend Servers Inherit

Backend servers inherit the proxy's full environment by default, so variables
you exported in your shell are visible to them without being listed in env.
Entries in env always take precedence over inherited values.

Narrow this with inheritEnv when a server should not see unrelated secrets:

{
  "inheritEnv": ["HOME", "PATH", "LANG"],
  "mcpServers": [
    {
      "name": "trusted",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "inheritEnv": true
    },
    {
      "name": "untrusted",
      "command": "some-third-party-server",
      "inheritEnv": false,
      "env": { "API_KEY": "${THIRD_PARTY_KEY}" }
    }
  ]
}

Value	Effect
true (default)	Pass the proxy's full environment through
false	Pass only the stdio transport's safe defaults (PATH, HOME, SHELL, …)
string[]	Pass only the named variables, plus the transport's safe defaults

Uncompressed Tool Descriptions

Before a tool has been compressed, the proxy shows its original description.
Set compressionFallbackBehavior to "blank" to show nothing instead, so
uncompressed tools cost no context while you work through them:

{
  "compressionFallbackBehavior": "blank",
  "mcpServers": []
}

This affects only tools with no cached compressed description. Compressed
tools, expanded tools, and anything matching noCompressTools are unchanged.

Server Initialization and Timeouts

The proxy initializes all configured MCP servers in parallel before becoming ready. Each server connection is wrapped with a timeout to prevent indefinite hanging:

• Default timeout: 30 seconds (if not specified)
• Global timeout: Set defaultTimeout in config to change the default for all servers
• Per-server timeout: Set timeout on individual servers to override the default

{
  "defaultTimeout": 60,
  "mcpServers": [
    {
      "name": "fast-server",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    {
      "name": "slow-server",
      "command": "python",
      "args": ["slow_mcp_server.py"],
      "timeout": 120
    }
  ]
}

Behavior:

• All servers initialize in parallel (not sequentially)
• If a server exceeds its timeout, it's marked as failed but doesn't block other servers
• The proxy reports ready only after all servers have either connected or timed out
• This ensures all available tools are loaded before the MCP client can query them

Why this matters: Without proper timeout handling, a single hanging server could make the entire proxy unresponsive.

Tool Filtering Patterns

Exclude Tools - Remove tools from the tool list entirely:

Use the excludeTools field to filter out unwanted tools using wildcard patterns (case-insensitive):

{
  "mcpServers": [...],
  "excludeTools": [
    "github__delete_*",     // Exclude all GitHub delete tools
    "*__experimental*",     // Exclude all experimental tools
    "filesystem__write_*",  // Exclude filesystem write tools
    "set_*"                 // Exclude management tools starting with set_
  ]
}

No-Compress Tools - Keep tools but never compress their descriptions:

Use the noCompressTools field to bypass compression for specific tools (descriptions pass through unchanged):

{
  "mcpServers": [...],
  "noCompressTools": [
    "filesystem__*",        // Never compress filesystem tool descriptions
    "*__help",              // Never compress help commands
    "github__search_*"      // Never compress GitHub search tools
  ]
}

Pattern Examples:

• "serverName__*" - All tools from specific server
• "*__toolPattern*" - Tools matching pattern from any server
• "exact_tool_name" - Exact tool name match

Use Cases:

• excludeTools: Remove dangerous tools, unwanted features, or tools not relevant to your workflow
• noCompressTools: Preserve detailed descriptions for complex tools where compression might lose important information

Configuration Aggregation

Both config files are loaded and combined:

1. Load user config (~/.mcp-compression-proxy/servers.json)
2. Load project config (./servers.json)
3. Aggregate servers from both configs
4. Aggregate exclude and noCompress patterns from both configs
5. Apply exclude patterns to filter tools
6. Apply noCompress patterns to bypass compression

This allows:

• Personal defaults in user config
• Team/project-specific servers in project config
• Fine-grained tool filtering with exclude patterns
• Selective compression bypass with noCompress patterns

Environment Variables

For the compression proxy (set in your MCP client config):

• LOG_LEVEL - Logging level (debug, info, warn, error). Default: info

For MCP servers (set in servers.json using ${VAR_NAME} syntax):

• GITHUB_TOKEN - GitHub personal access token (if using GitHub MCP server)
• Any other environment variables required by your configured MCP servers

See Environment Variable Expansion for details on using variables in your server configuration.

Command-Line Options

--clear-cache - Clear the persistent compression cache and exit

# If installed via npm
mcp-compression-proxy --clear-cache

# If installed from source
node dist/index.js --clear-cache

Debugging

1. Enable debug logging in your MCP client config:

{
  "mcpServers": {
    "compression-proxy": {
      "command": "mcp-compression-proxy",
      "env": {
        "LOG_LEVEL": "debug"
      }
    }
  }
}

2. View logs (for Claude Desktop):

• macOS: ~/Library/Logs/Claude/mcp*.log
• Windows: %APPDATA%\Claude\Logs\mcp*.log

3. Check for common issues:

• Ensure all configured MCP servers are accessible and properly configured
• Verify environment variables are correctly expanded
• Check that Node.js version is 18 or higher

💡 Best Practices

Good Compression

Preserves:

• Core functionality
• Key parameters
• Critical constraints
• Return types

Removes:

• Verbose explanations
• Redundant phrases
• Non-critical examples
• Marketing language

Example

Original (42 tokens):

"Searches for files in the specified directory and its subdirectories using
glob patterns. Supports wildcards like *, **, and ?. Returns an array of
matching file paths. Case-sensitive by default."

Compressed (12 tokens):

"Search files by glob pattern (*, **, ?), case-sensitive, returns paths"

❓ FAQ

Q: What MCP clients are supported?

Any MCP-compatible client: Claude Desktop, Cline, Continue.dev, or custom agents.

Q: How much context does compression save?

Typically 50-80% reduction in token count for tool listings while preserving critical information.

Q: Do I need to restart after adding servers?

Yes, restart your MCP client to load the new configuration. No rebuild needed when using JSON configuration.

Q: Can I use multiple MCP servers?

Yes! That's the primary use case. Add as many as you need in your servers.json configuration file.

Q: Is compression permanent?

Compressed descriptions are persisted to disk at ~/.mcp-compression-proxy/cache.json and automatically restored on server restart. Session-based expansions are temporary and reset per session.

Q: Where is the compression cache stored?

Cache is stored at ~/.mcp-compression-proxy/cache.json. Use --clear-cache flag to clear it if needed.

Q: Works with local LLMs?

Yes! Works with any MCP-compatible setup, including local models.

Q: How do I add a new MCP server?

Edit your servers.json configuration file (in ~/.mcp-compression-proxy/ or project root), add your server config, and restart your MCP client. No rebuild needed.

More: See CONTRIBUTING.md, SECURITY.md, tests/README.md

🧪 Testing

Comprehensive test suite included:

npm test                      # Run all tests
npm run test:unit             # Unit tests only
npm run test:integration      # Integration tests only
npm run test:e2e              # End-to-end tests only
npm run test:e2e:real-llm     # Real LLM integration tests (requires Ollama)
npm run test:coverage         # Generate coverage report

See tests/README.md for details.

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Quick start:

1. Fork the repository
2. Create your feature branch
3. Make your changes and test
4. Commit using Conventional Commits
5. Open a Pull Request

Note: This project follows a Code of Conduct.

🔗 Complementary Projects

Maximize your MCP workflow with these complementary tools:

Local Skills MCP

Portable, reusable prompt libraries for any MCP client

While MCP Compression Proxy optimizes your tool descriptions, Local Skills MCP provides expert-level prompt instructions that work across any MCP-compatible client.

Perfect combination:

• MCP Compression Proxy - Aggregates and compresses tool descriptions (50-80% token reduction)
• Local Skills MCP - Provides expert skills with lazy loading (~50 tokens/skill)

Together they enable:

• 🎯 Optimized context usage across tools AND prompts
• 🔄 Portable workflows that work with Claude, Cline, Continue.dev, and more
• ⚡ Efficient AI interactions with minimal context consumption
• 🚀 Professional-grade AI agent capabilities

Learn more about Local Skills MCP →

💖 Support This Project

If you find MCP Compression Proxy useful, please consider supporting its development!

Ways to support:

• ⭐ Star this repository
• 💰 Sponsor via the badges above
• 🐛 Report bugs and suggest features
• 📝 Contribute code or documentation

📄 License

MIT License - see LICENSE file. Copyright © 2025 KDPA

🙏 Acknowledgments

Built with Model Context Protocol SDK

---