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 7-prompt mixed session where all 4 MCP servers are configured but GitHub/Stitch used only at session start/end, Native MCP wastes ~16,300 tokens on schema descriptions for servers never invoked.

Real data: These tool counts come from live MCP servers queried via LeanProxy. See the methodology in our data-driven analysis.

The Solution: LeanProxy Gateway

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

• Single router schema: Only 2 tools (invoke_tool, list_tools) = ~110 tokens vs 16,300+ 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 (7-prompt session, 4 MCP servers)

Real-World Working Sessions

These numbers come from actual tool invocations across your MCP servers:

Session A: Morning Sport Check (Garmin + Intervals.icu, 4 prompts)

Session B: Dev Session (GitHub + Stitch, 5 prompts)

Session C: Full Day Workflow (All 4 MCP servers, 7 prompts)

Key insight: You don't need every server on every prompt. With LeanProxy, each tool loads JIT (~500 tokens) only when actually called, slashing the ~16,300 token tax to ~500 per invocation.

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 16,300-token MCP schema at 100% cache hit still costs:

16,300 tokens × 0.25x = 4,075 "effective" tokens worth of money

Real Comparison: Native MCP vs LeanProxy (Live MCP Data)

Native MCP sends tool schemas every prompt at 0.25x cache read. LeanProxy sends only ~110 router 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.

Provider Caching on "Same Input Context"

For MCP tool schemas that are identical every request, caching only reduces cost by 75% — you're still paying for the read. The "same input context" scenario:

Critical insight: With "same input context" caching, 100% cache hit STILL costs at 0.25x. LeanProxy sends only ~110 tokens, making cache read cost negligible (27.5 tokens). This is the real advantage.

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: 16,300 tokens × 100 sessions × 0.25x cache read / 1M (GPT-4o-mini) or / 1M (Sonnet)

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. See "Provider Caching on Same Input Context" above for the math.

Key Features

Quick Start

Installation

# macOS/Linux via Homebrew
brew tap mmornati/leanproxy-mcp https://github.com/mmornati/leanproxy-mcp
brew install leanproxy-mcp

# Download binary (auto-detects OS/arch)
VERSION=${VERSION:-$(curl -sL https://api.github.com/repos/mmornati/leanproxy-mcp/releases/latest | sed -n 's/.*"tag_name": *"\([^"]*\)".*/\1/p')}
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m)
[ "$ARCH" = "x86_64" ] && ARCH="amd64"
[ "$ARCH" = "arm64" ] && ARCH="arm64"
curl -fsSL "https://github.com/mmornati/leanproxy-mcp/releases/download/${VERSION}/leanproxy-mcp_${VERSION#v}_${OS}_${ARCH}.tar.gz" -o leanproxy-mcp.tar.gz
tar -xzf leanproxy-mcp.tar.gz
chmod +x leanproxy-mcp && sudo mv leanproxy-mcp /usr/local/bin/
rm leanproxy-mcp.tar.gz

# Override version: VERSION=v0.5.2 ...

# 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 run --stdio

# Run in dry-run mode to see potential savings
leanproxy-mcp server run --dry-run --stdio

# Generate a token savings report
leanproxy-mcp report --output report.md

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-mcp 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