mcp-compressor

MCP Compression Proxy service for PVE.

Wraps any existing MCP server and reduces tool-description token usage by exposing only a tiny discovery interface to the agent:

• list_tools() — compact list of {name, brief_description}

• get_tool_schema(tool_name) — full JSON schema + docs for one tool (cached)

• invoke_tool(tool_name, arguments) — execute and return result

• get_server_info() — metadata about connected upstream servers

Upstream tools are namespaced as mcp__<server>__<tool> to avoid collisions across servers.

Quick start

CLI / uvx mode (single upstream)

# stdio command upstream
uvx mcp-compressor "npx -y @modelcontextprotocol/server-filesystem /tmp"

# SSE URL upstream
uvx mcp-compressor "http://localhost:8080/sse" --server-name fetch --transport stdio

Service mode (multi-upstream)

Create config.yaml:

servers:
  - name: filesystem
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    cache_ttl: 300
    max_tools: 100

  - name: fetch
    url: http://localhost:8080/sse
    cache_ttl: 300
    max_tools: 50

cache_ttl: 300
max_tools: 100
log_level: INFO
host: 127.0.0.1
port: 8000
transport: sse

Run:

uvx mcp-compressor --config config.yaml --transport sse

Or install as a systemd service on PVE:

uv pip install -e .
mcp-compressor --config /etc/mcp-compressor.yaml --transport sse

Related MCP server: mcp-compressor

Configuration

Each upstream server accepts either:

• command + args + optional env for stdio MCP servers

• url for SSE MCP servers

Hermes / Bob mcp.json example

{
  "mcpServers": {
    "compressor": {
      "command": "uvx",
      "args": [
        "mcp-compressor",
        "npx -y @modelcontextprotocol/server-filesystem /tmp"
      ]
    }
  }
}

For service mode:

{
  "mcpServers": {
    "compressor": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

How it works

1. The proxy connects to every configured upstream MCP server on startup.

2. list_tools returns a short, stable list of namespaced names and one-line descriptions.

3. When the agent calls get_tool_schema, the proxy fetches the full schema for that single tool from the upstream server and caches it for cache_ttl seconds.

4. invoke_tool forwards the call to the correct upstream server with the original tool name and returns the result.

This keeps the agent context small while preserving the full MCP contract.

Development

uv sync --extra dev
uv run pytest
uv run ruff check src tests
uv run mypy src

License

MIT