leanproxy-mcp

LeanProxy-MCP

LeanProxy-MCP is a lightweight, local CLI proxy that sits between your IDE and MCP servers — acting as a Token Firewall that cuts token waste and protects sensitive data before it reaches LLM providers.

In the pay-per-use AI era (May 2026+), every token costs money. LeanProxy slashes your token bill by replacing the "schema tax" of Native MCP with a gateway pattern that loads tool definitions only when needed.

The Problem: MCP Schema Tax

When you connect multiple MCP servers, each injects tool schemas into every LLM request — even when you never use that server. This compounds quickly:

In a 20-prompt coding session where GitHub is called only twice, Native MCP wastes 61,654 tokens (99.7% overhead) on schema descriptions the agent never needed.

The Solution: LeanProxy Gateway

LeanProxy uses a gateway pattern with Just-In-Time schema loading:

• Single router schema: Only 2 tools (invoke_tool, search_tools) = ~110 tokens vs 3,000+ for Native MCP
• On-demand tool registration: Backend server schemas load only when actually invoked
• Session-aware caching: Tool schemas persist across the session without per-request overhead

Real Token Savings (20-prompt session, 2 GitHub ops)

The Cache Read Cost Fallacy

Providers advertise prompt caching as "free" or "90% savings" — but cache reads aren't free.

When a prompt cache hit occurs, you still pay for reading from cache:

• OpenAI: Cache reads at 0.25x input token price
• Anthropic: Cache reads at 0.25x input token price
• DeepSeek: Cache reads at 0.25x input token price
• Google Gemini: Cache reads at ~0.25x input token price

This means 100% cache hit doesn't mean 100% free. A 30,000-token MCP schema at 100% cache hit still costs:

30,000 tokens × 0.25x = 7,500 "effective" tokens worth of money

Real Comparison: Native MCP vs LeanProxy

Native MCP sends ~3,000 tokens/server × 0.25x cache read. LeanProxy sends ~110 tokens regardless of backend servers.

The key insight: With Native MCP + caching, you pay for every tool schema on every request (at 0.25x). LeanProxy sends only the router schema — the backend tool schemas only load when actually invoked.

Monthly Total Token Savings (100 sessions/month)

Native MCP sends tool schemas every request (at 0.25x cache read). LeanProxy only sends router schema.

Formula: 3,000 tokens/server × servers × 20 prompts × 100 sessions × 0.25x cache read

Should You Use Caching with MCP?

Key insight: For MCP tool schemas that are identical every request, caching only reduces cost by 75% — you're still paying for the read. LeanProxy eliminates the overhead entirely.

Key Features

Quick Start

Installation

# macOS/Linux via Homebrew
brew tap mmornati/leanproxy-mcp
brew install leanproxy-mcp

# Download binary from releases
curl -fsSL https://github.com/mmornati/leanproxy-mcp/releases/latest/download/leanproxy-mcp -o leanproxy-mcp
chmod +x leanproxy-mcp && sudo mv leanproxy-mcp /usr/local/bin/

# Build from source
git clone https://github.com/mmornati/leanproxy-mcp.git
cd leanproxy-mcp && make build

Basic Usage

# Start the proxy with a local MCP server
leanproxy-mcp server --stdio "npx @modelcontextprotocol/server-filesystem ./my-project"

# Run in dry-run mode to see potential savings
leanproxy-mcp server --dry-run --stdio "npx @modelcontextprotocol/server-filesystem ./my-project"

# Generate a token savings report
leanproxy-mcp compactor --manifest ./mcp.json

IDE Configuration

LeanProxy can be configured as an MCP server in your IDE. For detailed setup instructions, see the Installation Guide.

OpenCode Example

Add to your ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "leanproxy": {
      "type": "local",
      "command": ["leanproxy-mcp", "server", "run", "--stdio"],
      "enabled": true
    }
  }
}

Other IDEs (Claude Desktop, Cursor, Windsurf): see Installation Guide.

Verification

leanproxy server list

Build from Source

Prerequisites

• Go 1.25 or later
• Git

Commands

make build        # Build all platform binaries to dist/
make build-local  # Build for current platform only
make test         # Run all tests
make lint         # Run linter
make install      # Build and install to $GOPATH/bin

Documentation

For detailed documentation, see:

License

MIT License