Commands Reference¶

Complete reference for all LeanProxy-MCP CLI commands.

Main Command¶

leanproxy-mcp [command] [flags]

Global Flags¶

Flag	Type	Description
`--config`	string	Path to config file
`-n, --dry-run`	bool	Preview without making changes
`--log-level`	string	Log level (debug, info, warn, error)
`-v, --verbose`	bool	Enable verbose logging
`-h, --help`	bool	Show help

Available Commands¶

Command	Description
`add`	Install an MCP server from the registry
`serve`	Start the JSON-RPC streaming proxy
`server`	Manage MCP server configurations
`bouncer`	Manage redaction settings
`compactor`	Manage manifest caching
`cache`	Inspect and manage the tool cache
`status`	Display real-time server status
`savings`	Display token savings statistics
`cost`	Display token cost attribution statistics
`report`	Generate token savings report
`doctor`	Run diagnostic checks on the installation
`marketplace`	Interact with the MCP Registry marketplace
`migrate`	Import MCP configs from other tools
`completion`	Generate shell completions
`namespace`	Manage hierarchical namespaces
`version`	Print version information

`add` - Install Server from Registry¶

Install an MCP server from the local MCP Registry cache. Resolves the registry entry, merges it into leanproxy_servers.yaml, and prints a token-cost preview.

If the cache is empty or stale, run leanproxy marketplace sync first.

Usage¶

leanproxy-mcp add <server-id> [flags]

Aliases¶

install

Flags¶

Flag	Type	Default	Description
`--force`	bool	false	Overwrite an existing server definition with the same name
`--stop-existing`	bool	true	Gracefully stop any running server with the same name before replacing
`--graceful-wait`	int	10	Seconds to wait for graceful stop before proceeding (0 = no wait)
`-y, --yes`	bool	false	Skip the confirmation prompt when overwriting
`-n, --dry-run`	bool	false	Preview the install without writing the config
`--i-understand-the-risks`	bool	false	Acknowledge low-trust server warning and proceed

Examples¶

# Sync the registry first
leanproxy marketplace sync

# Search for a server
leanproxy marketplace search github

# Install a server from the registry
leanproxy add github

# Force overwrite an existing server
leanproxy add filesystem --force

# Preview installation without writing config
leanproxy add github --dry-run

Output¶

Registry entry: github (41 tools, trust score: 85/100)
Token impact:
  Native MCP:   ~4,100 tokens per request
  LeanProxy:    ~110 tokens per request
  Savings:      ~3,990 tokens (97.3%)

Server 'github' added successfully.

Low-trust servers (score < 40) require --i-understand-the-risks:

Warning: Server 'experimental-db' has a low trust score of 25/100.
This server may be unmaintained or from an untrusted publisher.
Use --i-understand-the-risks to install anyway.

How It Works¶

Lookup: Searches the local registry cache for the server ID
Preview: Computes a token-cost snapshot showing savings
Trust Check: Verifies the server's trust score; prompts if low
Install: Merges the server definition into leanproxy_servers.yaml
Stop Existing: Gracefully stops any running instance with the same name

`serve` - Start Proxy Server¶

Start the LeanProxy-MCP proxy server that listens for connections and forwards JSON-RPC requests.

Usage¶

leanproxy-mcp serve [flags]

Flags¶

Flag	Type	Default	Description
`--listen`	string	`127.0.0.1:8080`	Address to listen on
`--upstream`	string	`http://localhost:8081`	Upstream JSON-RPC server URL
`--dashboard-bind`	string	`127.0.0.1:9090`	Dashboard bind address. Set to `off` or empty to disable
`--dashboard-token`	string	`""`	Bearer token for dashboard access from non-loopback addresses
`--metrics-bind`	string	`""`	Metrics endpoint bind address (e.g. `127.0.0.1:9091`). Set to `off` or empty to disable
`--cache-strategy`	string	`off`	Cache breakpoint injection strategy: `off`, `aggressive`, `balanced`
`--embed-provider`	string	`""`	Embedding provider for semantic cache: `ollama` or `openai` (empty = disabled)
`--embed-pool-size`	int	`4`	Embedder worker pool size
`--ollama-url`	string	`http://localhost:11434`	Ollama server URL
`--ollama-model`	string	`nomic-embed-text`	Ollama embedding model
`--openai-model`	string	`text-embedding-3-small`	OpenAI embedding model
`--providers-config`	string	`""`	Path to providers config file for provider detection
`--model-router`	bool	false	Enable per-tool model routing based on complexity tier
`--model-router-config`	string	`""`	Path to model router YAML config
`--sidecar-provider`	string	`""`	Sidecar provider (`ollama`) for local LLM redaction (empty = disabled)
`--sidecar-model`	string	`llama3.1:8b`	Sidecar model name
`--sidecar-url`	string	`http://localhost:11434`	Sidecar server URL

Examples¶

# Start proxy server
leanproxy-mcp serve

# Listen on custom address
leanproxy-mcp serve --listen 0.0.0.0:9090

# Custom upstream server
leanproxy-mcp serve --upstream http://localhost:9000

# With verbose logging
leanproxy-mcp serve --verbose

# Enable web dashboard on default port
leanproxy-mcp serve --dashboard-bind 127.0.0.1:9090

# Enable metrics endpoint
leanproxy-mcp serve --metrics-bind 127.0.0.1:9091

# Enable semantic cache with Ollama embeddings
leanproxy-mcp serve --embed-provider ollama --ollama-url http://localhost:11434

# Enable model routing with custom config
leanproxy-mcp serve --model-router --model-router-config ./model-router.yaml

# Enable sidecar LLM redaction
leanproxy-mcp serve --sidecar-provider ollama --sidecar-model llama3.1:8b

# Cache breakpoint injection (Anthropic)
leanproxy-mcp serve --cache-strategy aggressive

# Full featured server
leanproxy-mcp serve \
  --dashboard-bind 127.0.0.1:9090 \
  --metrics-bind 127.0.0.1:9091 \
  --embed-provider ollama \
  --cache-strategy balanced

`server` - Manage MCP Servers¶

Add, remove, list, enable, or disable MCP servers.

Usage¶

leanproxy-mcp server [command]

Subcommands¶

Command	Description
`add`	Add a new MCP server
`remove`	Remove an MCP server
`list`	List all configured servers
`enable`	Enable a disabled server
`disable`	Disable an enabled server
`run`	Run leanproxy as an MCP stdio server

`server run` - Run Stdio Server¶

Run leanproxy-mcp as an MCP server in stdio mode. This command reads JSON-RPC requests from stdin and writes responses to stdout, proxying requests to configured MCP servers.

Usage¶

leanproxy-mcp server run --stdio [flags]

Flags¶

Flag	Type	Default	Description
`--stdio`	bool	false	Run in stdio mode (required)
`--config`	string	`~/.config/leanproxy_servers.yaml`	Path to config file
`--log-file`	string	""	Path to log file
`--log-level`	string	`info`	Log level (debug, info, warn, error)
`-v, --verbose`	bool	false	Enable verbose logging

Examples¶

# Run in stdio mode with default config
leanproxy-mcp server run --stdio

# Run with logging
leanproxy-mcp server run --stdio --log-file /tmp/leanproxy.log --log-level debug

# Run with custom config
leanproxy-mcp server run --stdio --config /path/to/config.yaml

# Dry-run mode
leanproxy-mcp server run --dry-run --stdio

OpenCode Configuration¶

To use with OpenCode, add to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "leanproxy": {
      "type": "local",
      "command": ["leanproxy-mcp", "server", "run", "--stdio"],
      "enabled": true
    }
  }
}

`server add` - Add Server¶

Add a new MCP server configuration.

Usage¶

leanproxy-mcp server add <name> <command> [args...] [flags]

Flags¶

Flag	Type	Description
`--cwd`	string	Working directory
`--env`	stringArray	Environment variables (KEY=value)
`--transport`	string	Transport type (stdio, http, sse)

Examples¶

# Add filesystem server (stdio)
leanproxy-mcp server add filesystem "npx -y @modelcontextprotocol/server-filesystem" "./"

# Add GitHub server
leanproxy-mcp server add github "npx -y @modelcontextprotocol/server-github"

# Add with environment variables
leanproxy-mcp server add myserver "npx -y my-server" --env API_KEY=xxx --env SECRET=yyy

# Add HTTP transport server
leanproxy-mcp server add http-server "http://localhost:8081" --transport http

Output¶

Server 'filesystem' added successfully.

`server remove` - Remove Server¶

Remove an MCP server configuration.

Usage¶

leanproxy-mcp server remove <name> [flags]

Examples¶

leanproxy-mcp server remove filesystem

Output¶

Server 'filesystem' removed.

`server list` - List Servers¶

List all configured MCP servers.

Usage¶

leanproxy-mcp server list [flags]

Flags¶

Flag	Type	Description
`--source`	string	Filter by source (opencode, claude, vscode, cursor, generic)

Examples¶

# List all servers
leanproxy-mcp server list

# Filter by source
leanproxy-mcp server list --source opencode

Output¶

NAME        STATUS    TRANSPORT  SOURCE    COMMAND
filesystem enabled   stdio     generic   npx -y @modelcontextprotocol/server-filesystem ./
github     disabled  stdio     generic   npx -y @modelcontextprotocol/server-github

If no servers configured:

No servers configured.

`server health` - Health Check¶

Check if an MCP server is healthy and responding. This command sends a ping request to the MCP server to verify it's working.

Usage¶

leanproxy-mcp server health <server_name> [flags]

Flags¶

Flag	Type	Default	Description
`--timeout`	duration	10s	Health check timeout
`--config`	string	-	Path to leanproxy_servers.yaml config file

Examples¶

# Check health of garmin server
leanproxy-mcp server health garmin

# Check health with custom timeout
leanproxy-mcp server health garmin --timeout 30s

Output (Server healthy)¶

✓ Server "garmin" is healthy (status: running, uptime: 5m30s)
  Note: Connected to running LeanProxy instance

Output (Server was stopped, restarted)¶

Note: Found running LeanProxy (PID: 1656) but server "garmin" may have stopped
      Attempting to restart server...
✓ Server "garmin" is healthy (latency: 2.1s)
  Note: Server was stopped in running LeanProxy, restarted successfully

Output (No running LeanProxy)¶

Note: No running LeanProxy instance found
time=2026-05-05T21:18:16.467+02:00 level=INFO msg="worker pool started" workers=4 queue_size=1000
time=2026-05-05T21:18:16.469+02:00 level=INFO msg="server spawned" name=garmin pid=91333
✓ Server "garmin" is healthy (latency: 1.7s)
  Note: Started new LeanProxy instance for health check

How It Works¶

Check running LeanProxy: First checks if there's a running LeanProxy instance
Check server status: If found, checks if the server is marked as "running" in the status file
Connect or restart:
If server is running → returns healthy immediately
If server is stopped but LeanProxy is running → restarts the MCP server
If no LeanProxy running → starts a new one just for health check
Send ping: Sends MCP protocol ping request to verify responsiveness

Use Cases¶

CI/CD verification: Verify MCP servers are healthy before running tests
Monitoring: Quick status check without using LLM tokens
Debugging: Verify a specific server is responding

`server enable` - Enable Server¶

Enable a disabled MCP server.

Usage¶

leanproxy-mcp server enable <name>

Examples¶

leanproxy-mcp server enable github

Output¶

Server 'github' enabled.

`server disable` - Disable Server¶

Disable an enabled MCP server.

Usage¶

leanproxy-mcp server disable <name>

Examples¶

leanproxy-mcp server disable github

Output¶

Server 'github' disabled.

`bouncer` - Redaction Settings¶

Manage Bouncer redaction (token firewall) settings.

Usage¶

leanproxy-mcp bouncer [command]

Subcommands¶

Command	Description
`list-patterns`	List all active redaction patterns
`validate-patterns`	Validate custom patterns from config

`bouncer list-patterns` - List Patterns¶

List all active redaction patterns.

Usage¶

leanproxy-mcp bouncer list-patterns

Examples¶

leanproxy-mcp bouncer list-patterns

Output¶

# Built-in Patterns
  - aws-access-key: AWS Access Key ID (20 characters, starts with AKIA)
  - github-classic-pat: GitHub Classic Personal Access Token (starts with ghp_)
  - github-fine-grained-pat: GitHub Fine-grained PAT (starts with github_pat_)
  - stripe-secret-key: Stripe Live Secret Key (starts with sk_live_)
  - stripe-publishable-key: Stripe Live Publishable Key (starts with pk_live_)
  - generic-api-key: Generic API key pattern (case-insensitive)
  - bearer-token: JWT Bearer token (three base64url segments)
  - env-var-value: Environment variable assignment

`bouncer validate-patterns` - Validate Patterns¶

Validate custom redaction patterns from config.

Usage¶

leanproxy-mcp bouncer validate-patterns

Examples¶

leanproxy-mcp bouncer validate-patterns --config custom.yaml

Output (success)¶

All patterns valid.

Output (error)¶

Error: invalid regex pattern '[' at line 3

`compactor` - Token Optimization via Manifest Distillation¶

The compactor optimizes token usage by compressing MCP server tool descriptions using an LLM.

What it does¶

When an MCP server starts, it provides a manifest listing all its tools with descriptions. These descriptions can be verbose, causing unnecessary token usage on every LLM request.

The compactor: 1. Takes each tool's description 2. Uses an LLM to compress it to ~50 characters while preserving technical accuracy 3. Caches the optimized version to avoid re-distillation

This is transparent to users - LeanProxy automatically uses distilled manifests when available.

Example¶

Before (raw manifest):

Tool: "read_file" - "Reads the complete contents of a file from the filesystem, supporting both text and binary formats, with optional encoding selection"

After (distilled):

Tool: "read_file" - "Read file contents from filesystem"

Configuration¶

The compactor requires LLM configuration in leanproxy_servers.yaml:

compactor:
  enabled: true
  llm-endpoint: "https://api.openai.com/v1/chat/completions"
  llm-api-key: "${OPENAI_API_KEY}"
  llm-model: "gpt-4o-mini"

Usage¶

leanproxy-mcp compactor [command]

Subcommands¶

Command	Description
`rebuild`	Force re-distillation of server manifests

`compactor rebuild` - Rebuild Manifests¶

Force re-distillation of server manifests to refresh stale discovery signatures.

When to use: - Tool descriptions have changed in the MCP server - You want to re-optimize with a different LLM model - The cache became stale

Usage¶

leanproxy-mcp compactor rebuild [server-name] [flags]

Flags¶

Flag	Type	Default	Description
`--all`	bool	false	Rebuild all servers

Examples¶

# Rebuild a specific server
leanproxy-mcp compactor rebuild github

# Rebuild all servers
leanproxy-mcp compactor rebuild --all

# Dry run
leanproxy-mcp compactor rebuild github --dry-run

`cache` - Tool Cache Inspector¶

Inspect and manage the persisted tool cache. The cache stores tool signatures from MCP servers, enabling offline search and fast tool listing without starting backend servers.

Usage¶

leanproxy-mcp cache [flags]
leanproxy-mcp cache [command]

Subcommands¶

Command	Description
`stats`	Show Anthropic prompt cache hit rate statistics

Cache Location¶

The tool cache is stored at:

~/.config/leanproxy/toolcache/

Each server's tools are cached in a separate JSON file: - garmin.json - Intervals_icu.json - etc.

Flags¶

Flag	Type	Description
`--list`	bool	List all servers with cached tools
`--location`	bool	Show the cache directory location
`--server`	string	Show cached tools for a specific server
`--search`	string	Search cached tools by name or description
`--semantic`	bool	Show semantic cache hit/miss dashboard
`--clear`	bool	Clear cache for specified server (use with --server)
`--json`	bool	Output in JSON format

Examples¶

# Show cache location
leanproxy-mcp cache --location

# List servers with cached tools
leanproxy-mcp cache --list

# Show cached tools for a server
leanproxy-mcp cache --server garmin

# Search in cache (across all servers)
leanproxy-mcp cache --search activity

# Search within a specific server
leanproxy-mcp cache --server garmin --search sleep

# Clear cache for a server
leanproxy-mcp cache --clear --server garmin

# Show Anthropic prompt cache hit rate
leanproxy-mcp cache stats

# Show semantic cache hit/miss dashboard
leanproxy-mcp cache --semantic

# Show semantic cache data as JSON
leanproxy-mcp cache --semantic --json

`cache stats` - Cache Hit Rate¶

Show Anthropic prompt caching hit rate statistics including total requests, cache hits, hit rate percentage, tokens saved, and estimated dollar savings.

Usage¶

leanproxy-mcp cache stats [flags]

Flags¶

Flag	Type	Default	Description
`--json`	bool	false	Output in JSON format
`--model`	string	`claude-sonnet-4-20250514`	Anthropic model for cost estimation

Examples¶

# Show cache hit rate
leanproxy-mcp cache stats

# Show for a specific model
leanproxy-mcp cache stats --model claude-sonnet-4-20250514

# JSON output
leanproxy-mcp cache stats --json

Output¶

## Anthropic Prompt Caching Hit Rate

| Metric | Value |
|--------|-------|
| Total Requests | 1,234 |
| Cache Hits | 987 |
| Cache Misses | 247 |
| Hit Rate | 80.0% |
| Tokens Saved | 45,678 |
| Estimated Savings | $0.37 |
| Model | claude-sonnet-4-20250514 |

Output (--location)¶

Tool cache location: ~/.config/leanproxy/toolcache

Output (--list)¶

Servers with cached tools (2):

  - Intervals_icu
  - garmin

Use --server <name> to see tools for a specific server

Output (--search activity)¶

Intervals_icu (4 matches):
  get_activity_details
    Get detailed information for a specific activity from Intervals.icu
  get_activity_intervals
    Get interval data for a specific activity from Intervals.icu
  ...

garmin (18 matches):
  get_activities_by_date
    Get activities data between specified dates, optionally filtered by activity type
  ...

Total: 22 matches across 2 servers

Output (--server garmin)¶

Cached tools for garmin (100 total):

  garmin_get_activities_by_date
    Get activities data between specified dates, optionally filtered by activity type

        Args:
            start_date: Start date in YYYY-MM-DD format
            end_date: End date in YYYY-MM-DD format
            activity_type: Optional activity type filter (e.g., cycling, running, swimming)
         [start_date: string, end_date: string] {activity_type: string}

  garmin_get_activities_fordate
    Get activities for a specific date

        Args:
            date: Date in YYYY-MM-DD format
         [date: string]

`list_tools` - MCP Method¶

LeanProxy-MCP supports a list_tools MCP method that allows LLMs to list all tools available on a specific MCP server. This is particularly useful when used with OpenCode - the LLM first calls list_servers to get available servers, then list_tools to see tools on a specific server.

Request Format¶

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_tools",
    "arguments": {
      "server_name": "garmin",
      "max_description_chars": 200
    }
  }
}

Parameters¶

Parameter	Type	Required	Description
`server_name`	string	Yes	MCP server name (from `list_servers`). Identifies which server's tools to list.
`max_description_chars`	integer	No	Truncate descriptions to this length (default: 200, range: 50-500)

Response Format¶

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "github tools (12):\ngithub_create_issue: Create a new issue... [title: string, body: string] {labels: string}\ngithub_list_issues: List repository issues... [owner: string, repo: string] {state: string}\n..."
    }]
  }
}

Tool Display Format¶

Each tool is displayed with: - Name: tool_name (without server prefix in list_tools output) - Description: Full or truncated description - Parameters: - [required: type] - Required parameters in brackets - {optional: type} - Optional parameters in braces

Example:

garmin tools (5):
get_activities: Get activities data between specified dates [start_date: string, end_date: string] {activity_type: string}
get_sleep_data: Get sleep data [start_date: string, end_date: string] {}

How Tool Caching Works¶

On First Call: When list_tools is called for a specific server for the first time (or after cache invalidation), LeanProxy-MCP:
Starts the specified MCP server (if not running)
Sends initialize request to the server
Sends tools/list request to the server
Caches the tool signatures locally in ~/.config/leanproxy/toolcache/
On Subsequent Calls: Tool signatures are loaded from the persistent cache, avoiding server startup.
Cache Invalidation: Cache is invalidated when:
leanproxy cache --clear --server <name> is called
Server configuration changes
Tool list changes are detected (if listChanged capability is supported)

Status File¶

When server run --stdio or serve is running, a status file is written to:

~/.config/leanproxy/status/current.json

This allows leanproxy status --running to detect running instances.

Status File Contents:

{
  "pid": 12345,
  "started_at": "2026-05-03T19:30:00+02:00",
  "listen_addr": "stdio",
  "servers": [
    {
      "name": "garmin",
      "status": "running",
      "request_count": 10,
      "error_count": 0,
      "restart_count": 1
    }
  ]
}

The status file is: - Written immediately when the server starts - Updated every 5 seconds while running - Removed when the server shuts down gracefully

`status` - Server Status¶

Display real-time status of all active proxied servers. Can show status either from running instances (via status file) or from configuration.

Usage¶

leanproxy-mcp status [flags]

Flags¶

Flag	Type	Default	Description
`--interval`	duration	`1s`	Watch mode refresh interval
`--json`	bool	false	Output in JSON format
`--running`	bool	false	Only show running instances from status file
`--server`	string	""	Filter by server name
`--verbose`	bool	false	Show additional details
`--watch`	bool	false	Continuously update

Status File¶

When using --running, status is read from the status file written by running instances:

~/.config/leanproxy/status/current.json

This file is created by: - leanproxy-mcp serve (HTTP proxy mode) - leanproxy-mcp server run --stdio (stdio mode, used by OpenCode)

Examples¶

# Basic status (from config)
leanproxy-mcp status

# Status from running instance only
leanproxy-mcp status --running

# Watch mode
leanproxy-mcp status --watch

# JSON output
leanproxy-mcp status --json

# Verbose with more details
leanproxy-mcp status --verbose

# Filter by server
leanproxy-mcp status --server filesystem

# Custom refresh interval
leanproxy-mcp status --watch --interval 500ms

Output (--running)¶

Running leanproxy instance (PID: 12345, started: 2026-05-03 19:30:00, listen: stdio)

SERVER       STATUS      UPTIME     LAST RESPONSE   RESTARTS
──────────────────────────────────────────────────────────────
garmin       running    0s         -          1
Intervals.icu running    0s         -          1

Note: The --running flag reads from the status file. If no instances are running, you'll see:

No running leanproxy instance found
No servers configured

Output (basic)¶

SERVER      STATUS    HEALTH    UPTIME    REQUESTS
filesystem Up        healthy  5m32s    1,234
github     Down     -         -         -

Output (JSON)¶

{
  "servers": [
    {
      "name": "filesystem",
      "status": "Up",
      "health": "healthy",
      "uptime": "5m32s",
      "requests": 1234
    }
  ]
}

Output (verbose)¶

SERVER      STATUS    HEALTH    UPTIME    REQUESTS  ERRORS  MEMORY
filesystem Up        healthy  5m32s    1,234    0       45MB
github     Down     -         -         -        -       -

`savings` - Token Savings¶

Display cumulative token savings statistics.

Usage¶

leanproxy-mcp savings [flags]

Flags¶

Flag	Type	Description
`--json`	bool	Output in JSON format
`--reset`	bool	Reset cumulative counters
`--server`	string	Filter by server name

Examples¶

# Show all savings
leanproxy-mcp savings

# JSON output
leanproxy-mcp savings --json

# Filter by server
leanproxy-mcp savings --server filesystem

# Reset counters
leanproxy-mcp savings --reset

Output¶

Total token savings: 45,678 (12.3%)
By server:
  filesystem: 32,456 (11.2%)
  github: 13,222 (14.1%)

Output (JSON)¶

{
  "total": 45678,
  "percentage": 12.3,
  "by_server": {
    "filesystem": {"savings": 32456, "percentage": 11.2},
    "github": {"savings": 13222, "percentage": 14.1}
  }
}

`cost` - Token Cost Attribution¶

Display token usage broken down by tool and server for the current session. This allows you to see which tools consume the most tokens.

Usage¶

leanproxy-mcp cost [flags]

Flags¶

Flag	Type	Description
`--by-tool`	bool	Show cost breakdown by tool only
`--by-server`	bool	Show cost breakdown by server only
`--json`	bool	Output in JSON format
`--reset`	bool	Reset cost counters

Examples¶

# Show full cost breakdown
leanproxy-mcp cost

# Show cost by tool only
leanproxy-mcp cost --by-tool

# Show cost by server only
leanproxy-mcp cost --by-server

# JSON output
leanproxy-mcp cost --json

# Reset counters
leanproxy-mcp cost --reset

Output (full breakdown)¶

=== Token Cost Summary ===
Total Session Tokens: 1234
Session Duration:     5m30s

=== Token Cost by Tool ===
github.create_issue: 450 tokens
github.list_issues: 350 tokens
filesystem.read_file: 280 tokens
filesystem.list_directory: 154 tokens

=== Token Cost by Server ===
github: 800 tokens
filesystem: 434 tokens

Output (--by-tool)¶

=== Token Cost Summary ===
Total Session Tokens: 1234
Session Duration:     5m30s

=== Token Cost by Tool ===
github.create_issue: 450 tokens
github.list_issues: 350 tokens
filesystem.read_file: 280 tokens
filesystem.list_directory: 154 tokens

Output (--by-server)¶

=== Token Cost Summary ===
Total Session Tokens: 1234
Session Duration:     5m30s

=== Token Cost by Server ===
github: 800 tokens
filesystem: 434 tokens

Output (JSON)¶

{
  "by_tool": [
    {"tool_name": "github.create_issue", "token_count": 450},
    {"tool_name": "github.list_issues", "token_count": 350},
    {"tool_name": "filesystem.read_file", "token_count": 280},
    {"tool_name": "filesystem.list_directory", "token_count": 154}
  ],
  "by_server": [
    {"server_name": "github", "token_count": 800},
    {"server_name": "filesystem", "token_count": 434}
  ],
  "total": 1234,
  "duration": "5m30s"
}

How It Works¶

The cost tracking system monitors token usage during tool invocations:

Token Estimation: When a tool is called, the system estimates token count from request/response size (using ~4 characters per token)
Per-Tool Tracking: Tokens are attributed to the specific tool that was invoked
Per-Server Tracking: Tokens are also aggregated by the MCP server that handled the request
Session Duration: The time since the session started is tracked

Status File Integration¶

Cost tracking data is also available via the status file at:

~/.config/leanproxy/status/current.json

The status file includes a cost_tracking section when enabled:

{
  "pid": 12345,
  "started_at": "2026-05-08T10:00:00+02:00",
  "listen_addr": "stdio",
  "servers": [...],
  "cost_tracking": {
    "by_tool": {"github.create_issue": 450, "github.list_issues": 350},
    "by_server": {"github": 800},
    "total": 1234,
    "enabled": true
  }
}

Use Cases¶

Identify expensive tools: Find which tools consume the most tokens
Cost allocation: Understand which MCP servers are driving costs
Optimization insights: Identify opportunities to optimize tool usage

`report` - Generate Report¶

Generate a Markdown-formatted report on token savings and security risks.

Usage¶

leanproxy-mcp report [flags]

Flags¶

Flag	Type	Description
`--json`	bool	Output JSON instead of Markdown
`--no-security`	bool	Exclude security events
`--output`	string	Output file path
`--session-id`	string	Generate for specific session
`--export`	string	Export raw cost data format (`csv`, `json`)
`--since`	string	Include entries since this date (YYYY-MM-DD, requires `--export`)

Examples¶

# Generate report
leanproxy-mcp report

# Output to file
leanproxy-mcp report --output savings.md

# JSON output
leanproxy-mcp report --json

# Exclude security
leanproxy-mcp report --no-security

# Export cost data as CSV
leanproxy-mcp report --export csv

# Export cost data as JSON
leanproxy-mcp report --export json

# Export cost data since a specific date
leanproxy-mcp report --export csv --since 2026-06-01

# Export to file
leanproxy-mcp report --export csv --output cost-report.csv

Output (Markdown)¶

# LeanProxy Session Report

## Summary
- Session ID: abc123
- Duration: 1h 23m
- Total Requests: 1,456

## Token Savings
| Server | Original | Redacted | Savings |
|--------|----------|---------|---------|
| filesystem | 45,678 | 32,222 | 29.4% |
| github | 12,345 | 9,876 | 20.0% |

## Security Events
| Type | Count |
|------|-------|
| api-key | 15 |
| bearer-token | 3 |

`migrate` - Import Configurations¶

Auto-detect and import MCP server configurations from other tools.

Usage¶

leanproxy-mcp migrate [flags]

Flags¶

Flag	Type	Description
`--dry-run`	bool	Preview scan results without importing
`--target`	string	Target config file path
`--validate-only`	bool	Only validate servers without importing
`--yes`	bool	Skip confirmation prompt

Examples¶

# Auto-detect all sources
leanproxy-mcp migrate

# Dry run (preview what would be imported)
leanproxy-mcp migrate --dry-run

# Skip confirmation
leanproxy-mcp migrate --yes

# Validate without importing
leanproxy-mcp migrate --validate-only

Output¶

Found 4 MCP server(s) from 1 source(s):

  OpenCode: 4 server(s)

  [1] nexus-dev (opencode) - /usr/bin/env
  [2] nexus-dev-test (opencode) - /usr/bin/env
  [3] garmin (opencode) - uvx
  [4] Intervals.icu (opencode) - /usr/bin/env

Import to ~/.config/leanproxy_servers.yaml? [y/N]:

`completion` - Shell Completions¶

Generate shell completion scripts.

Usage¶

leanproxy-mcp completion [shell]

Arguments¶

Shell	Description
`bash`	Bash completion
`zsh`	Zsh completion
`fish`	Fish completion
`powershell`	PowerShell completion

Examples¶

# Bash
leanproxy-mcp completion bash > /etc/bash_completion.d/leanproxy-mcp

# Zsh
leanproxy-mcp completion zsh > ~/.zsh/completions/_leanproxy-mcp

# Fish
leanproxy-mcp completion fish > ~/.config/fish/completions/leanproxy-mcp.fish

`marketplace` - MCP Registry Marketplace¶

Interact with the MCP Registry marketplace: sync the latest server index, search for available servers, and discover community MCP servers with trust scores and maintenance status.

Usage¶

leanproxy-mcp marketplace [command]

Subcommands¶

Command	Description
`sync`	Fetch and cache the MCP Registry index
`search`	Search MCP Registry servers by name or description

`marketplace sync` - Sync Registry Index¶

Download the latest MCP Registry server index and store it locally. The cached index is used by marketplace commands and kept up-to-date via periodic refresh.

Usage¶

leanproxy-mcp marketplace sync

Examples¶

# Sync the registry index
leanproxy-mcp marketplace sync

Output¶

Fetching registry index...
Registry index synced successfully (1,245 entries)
Cache stored at: ~/.config/leanproxy/registry/feed_index.json

`marketplace search` - Search Registry Servers¶

Search the local MCP Registry cache for servers matching the query. Displays a table with trust score, maintenance status, and download metrics.

Usage¶

leanproxy-mcp marketplace search <query> [flags]

Flags¶

Flag	Type	Default	Description
`--limit`	int	`25`	Maximum number of rows to display (1-200)

Examples¶

# Search for GitHub-related servers
leanproxy-mcp marketplace search github

# Search for database servers
leanproxy-mcp marketplace search database

# Limit results
leanproxy-mcp marketplace search filesystem --limit 10

Output¶

Search results for "github" (5 matches):

  NAME                      TRUST    STATUS      DOWNLOADS
  github                    85/100   maintained  12,450
  github-actions            72/100   maintained   3,210
  github-project-manager    45/100   beta          890
  githunter                 22/100   unmaintained   120
  github-enterprise         90/100   verified    45,600

Scores below 40 are considered low trust and require --i-understand-the-risks when installing.

`doctor` - Diagnostic Checks¶

Run diagnostic checks on the LeanProxy installation including injection security policy, quarantine status, configuration syntax, and file permissions.

Usage¶

leanproxy-mcp doctor [command] [flags]

Subcommands¶

Command	Description
`security`	Show injection security policy and quarantine status

`doctor security` - Security Diagnostic¶

Display the current injection security policy rules and quarantine status for prompt-injection protection.

Usage¶

leanproxy-mcp doctor security

Examples¶

# Show security diagnostics
leanproxy-mcp doctor security

Output¶

# Injection Security Diagnostic

## Policy Configuration

  Risk  80-100 -> block
  Risk  50- 79 -> quarantine
  Risk   1- 49 -> log

## Quarantine Status

  Quarantined payloads: 2
    - ~/.leanproxy/quarantine/a1b2c3d4-e5f6-7890-abcd-ef1234567890.json
    - ~/.leanproxy/quarantine/b2c3d4e5-f6a7-8901-bcde-fa1234567890.json

Total quarantined payloads: 2

`namespace` - Hierarchical Namespace Management¶

Manage hierarchical namespaces for organizing MCP servers. Namespaces allow multi-team organizations to manage access to MCP servers by grouping them under logical organizational units.

Usage¶

leanproxy-mcp namespace [command]

Subcommands¶

Command	Description
`list`	List all namespaces or tools in a namespace
`add`	Add a new namespace
`assign`	Assign a server to a namespace

`namespace list` - List Namespaces¶

List all configured namespaces or show details about a specific namespace.

Usage¶

leanproxy-mcp namespace list [namespace] [flags]

Flags¶

Flag	Type	Description
`--tools`	bool	List tools in the namespace

Examples¶

# List all namespaces
leanproxy-mcp namespace list

# List tools in a namespace
leanproxy-mcp namespace list engineering --tools

# Add a new namespace
leanproxy-mcp namespace add engineering --servers=github,jira --description="Engineering team"

# Assign a server to a namespace
leanproxy-mcp namespace assign engineering github

# List tools in a specific namespace
leanproxy-mcp namespace list engineering --tools

Output (all namespaces)¶

Configured namespaces:
  - engineering: Engineering team tools [2 servers]
  - ops: Operations infrastructure [2 servers]
  - engineering.frontend: Frontend team [1 servers]

Output (specific namespace)¶

Namespace: engineering
Description: Engineering team tools
Servers: [github jira]
Children: [frontend]

Output (tools in namespace)¶

Tools in namespace 'engineering':
  - engineering.github (server: github)
  - engineering.jira (server: jira)

`namespace add` - Add Namespace¶

Generate example configuration for a new namespace.

Usage¶

leanproxy-mcp namespace add <namespace> [flags]

Flags¶

Flag	Type	Description
`--servers`	string	Comma-separated list of servers
`--description`	string	Namespace description

Examples¶

# Add a new namespace
leanproxy-mcp namespace add engineering --servers=github,jira --description="Engineering team"

# Add with description
leanproxy-mcp namespace add frontend --description="Frontend team tools"

Output¶

Adding namespace 'engineering'
  Servers: github,jira
  Description: Engineering team

Note: Namespace configuration should be added to leanproxy.yaml
Example configuration:
  namespaces:
    engineering:
      servers:
        - github
        - jira
      description: "Engineering team"

`namespace assign` - Assign Server¶

Generate example configuration for assigning a server to a namespace.

Usage¶

leanproxy-mcp namespace assign <namespace> <server>

Examples¶

# Assign a server to a namespace
leanproxy-mcp namespace assign engineering github

Output¶

Assigning server 'github' to namespace 'engineering'

Note: This operation requires updating leanproxy.yaml
Add 'github' to the 'engineering' namespace servers list.

Configuration¶

Namespaces are configured in leanproxy.yaml under the namespaces key:

namespaces:
  engineering:
    description: "Engineering team tools"
    servers:
      - github
      - jira
    children:
      frontend:
        servers:
          - storybook
  ops:
    servers:
      - aws
      - kubernetes

Namespace Options¶

Field	Type	Description
`description`	string	Human-readable description of the namespace
`servers`	[]string	List of server IDs in this namespace
`children`	map	Nested namespaces (parent includes children)
`allowed_clients`	[]string	Clients allowed to access this namespace (supports `*` for wildcard)

Access Control Example¶

namespaces:
  restricted:
    description: "Restricted access namespace"
    allowed_clients:
      - "client1"
      - "client2"
      - "*"  # Wildcard allows any client
    servers:
      - secure-server
  public:
    description: "Public namespace (no access restrictions)"
    servers:
      - public-server

`version` - Version Info¶

Print version information.

Usage¶

leanproxy-mcp version

Output¶

 leanproxy-mcp version 0.5.2
 build date: 2026-05-04
 platform: darwin/arm64
 go: go1.25.5

Exit Codes¶

Code	Meaning
0	Success
1	General error
2	Configuration error
3	Network error
4	Permission error

Next Steps¶

Quick Start - Get started quickly
Configuration - Customize behavior
Troubleshooting - Common issues

Commands Reference¶

Main Command¶

Global Flags¶

Available Commands¶

add - Install Server from Registry¶

Usage¶

Aliases¶

Flags¶

Examples¶

Output¶

How It Works¶

serve - Start Proxy Server¶

Usage¶

Flags¶

Examples¶

server - Manage MCP Servers¶

Usage¶

Subcommands¶

server run - Run Stdio Server¶

Usage¶

Flags¶

Examples¶

OpenCode Configuration¶

server add - Add Server¶

Usage¶

Flags¶

Examples¶

Output¶

server remove - Remove Server¶

Usage¶

Examples¶

Output¶

server list - List Servers¶

Usage¶

Flags¶

Examples¶

Output¶

server health - Health Check¶

Usage¶

Flags¶

Examples¶

Output (Server healthy)¶

Output (Server was stopped, restarted)¶

Output (No running LeanProxy)¶

How It Works¶

Use Cases¶

server enable - Enable Server¶

Usage¶

Examples¶

Output¶

server disable - Disable Server¶

Usage¶

Examples¶

Output¶

bouncer - Redaction Settings¶

Usage¶

Subcommands¶

bouncer list-patterns - List Patterns¶

Usage¶

Examples¶

Output¶

bouncer validate-patterns - Validate Patterns¶

Usage¶

Examples¶

Output (success)¶

Output (error)¶

compactor - Token Optimization via Manifest Distillation¶

What it does¶

Example¶

Configuration¶

Usage¶

Subcommands¶

compactor rebuild - Rebuild Manifests¶

Usage¶

Flags¶

Examples¶

cache - Tool Cache Inspector¶

Usage¶

Subcommands¶

Cache Location¶

`add` - Install Server from Registry¶

`serve` - Start Proxy Server¶

`server` - Manage MCP Servers¶

`server run` - Run Stdio Server¶

`server add` - Add Server¶

`server remove` - Remove Server¶

`server list` - List Servers¶

`server health` - Health Check¶

`server enable` - Enable Server¶

`server disable` - Disable Server¶

`bouncer` - Redaction Settings¶

`bouncer list-patterns` - List Patterns¶

`bouncer validate-patterns` - Validate Patterns¶

`compactor` - Token Optimization via Manifest Distillation¶

`compactor rebuild` - Rebuild Manifests¶

`cache` - Tool Cache Inspector¶

`cache stats` - Cache Hit Rate¶

`list_tools` - MCP Method¶

`status` - Server Status¶

`savings` - Token Savings¶

`cost` - Token Cost Attribution¶

`report` - Generate Report¶

`migrate` - Import Configurations¶

`completion` - Shell Completions¶

`marketplace` - MCP Registry Marketplace¶

`marketplace sync` - Sync Registry Index¶

`marketplace search` - Search Registry Servers¶