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)

Monthly Dollar Savings (100 sessions/month)

Calculated at 80% input / 20% output token mix with May 2026 pricing.

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