Lazy MCP Proxy

A proxy tool that converts normal MCP servers to use a lazy-loading pattern, dramatically reducing initial context usage by 90%+ and enabling support for hundreds of commands.

Table of Contents

• Table of Contents
• Features
• Modes
  • Single-Server Mode (Legacy)
  • Multi-Server Mode (NEW!)
• Installation
• Usage
  • Multi-Server Mode (Recommended)
  • Single-Server Mode (Legacy)
    • Local MCP Servers
    • Remote MCP Servers
• Claude Desktop / OpenCode Integration
  • Multi-Server Mode (Recommended)
  • Single-Server Mode (Legacy)
• Example
• Development
• Publishing New Versions
  • For Maintainers
• Configuration Reference
  • Server Configuration Fields
  • Command Format
  • Environment Variables
  • Health Monitoring
  • Config Reload (SIGHUP)
• Benefits
• Documentation

Features

• Single-Server Mode: Wrap one MCP server with 3 meta-tools (legacy mode)
• Multi-Server Mode: Aggregate multiple MCP servers with on-demand discovery (NEW!)
• Lazy Loading: Only discover tools when needed, not upfront
• Batch Discovery: Discover multiple servers in one call
• 90%+ Context Reduction: From ~16K to ~1.5K tokens initially
• Background Health Monitoring: Probes all servers on startup and periodically; list_servers shows accurate health from the first call
• Hot Config Reload: Send SIGHUP to reload config without restarting — add, remove, or update servers on the fly

Modes

Single-Server Mode (Legacy)

Wraps one MCP server and exposes three meta-tools:

• list_commands - Returns command names and brief descriptions
• describe_commands - Accepts command_names: Array[String], returns full schemas
• invoke_command - Executes commands with command_name: String, parameters: Object

Multi-Server Mode (NEW!)

Aggregates multiple MCP servers and exposes four meta-tools:

• list_servers - Lists all configured MCP servers with health status
• list_commands - Discovers tools from specific server(s), supports batch discovery
• describe_commands - Gets detailed schemas from a server
• invoke_command - Executes commands from a specific server

Installation

Recommended: Use with npx to always get the latest version:

npx lazy-mcp@latest <server-command-or-url>

Or install globally (locks to specific version):

npm install -g lazy-mcp

Usage

Multi-Server Mode (Recommended)

Create a configuration file at ~/.config/lazy-mcp/servers.json:

{
  "mode": "multi-server",
  "servers": [
    {
      "name": "chrome-devtools",
      "description": "Chrome DevTools automation",
      "type": "local",
      "command": ["npx", "-y", "chrome-devtools-mcp@latest"]
    },
    {
      "name": "gitlab",
      "description": "GitLab API integration",
      "type": "local",
      "command": [
        "npx",
        "mcp-remote@latest",
        "https://gitlab.com/api/v4/mcp",
        "--static-oauth-client-metadata",
        "{\"scope\": \"mcp\"}"
      ]
    },
    {
      "name": "my-remote-server",
      "description": "Custom remote MCP server",
      "type": "remote",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  ],
  "healthMonitor": {
    "enabled": true,
    "interval": 30000,
    "timeout": 10000
  }
}

Then run:

# Using npx (recommended - always latest version)
npx lazy-mcp@latest --config ~/.config/lazy-mcp/servers.json

# Or via environment variable
LAZY_MCP_CONFIG=~/.config/lazy-mcp/servers.json npx lazy-mcp@latest

# Or if installed globally
lazy-mcp --config ~/.config/lazy-mcp/servers.json

Single-Server Mode (Legacy)

Local MCP Servers

# Run a Python MCP server
npx lazy-mcp@latest python my_server.py

# Run a Node.js server with arguments
npx lazy-mcp@latest node server.js --port 8080

# Run complex commands (use quotes)
npx lazy-mcp@latest "uvicorn server:app --host 0.0.0.0 --port 3000"

Remote MCP Servers

# Connect to a remote HTTP MCP server
npx lazy-mcp@latest http://localhost:3000/mcp

# With authentication headers
npx lazy-mcp@latest https://api.example.com/mcp --header "Authorization=Bearer token123"

# Multiple headers
npx lazy-mcp@latest https://api.example.com/mcp --header "X-API-Key=abc123" --header "User-Agent=my-app/1.0"

Claude Desktop / OpenCode Integration

Multi-Server Mode (Recommended)

Replace multiple MCP server entries with one aggregated proxy:

Before (5 separate MCP servers):

{
  "mcp": {
    "chrome-devtools": { "command": ["npx", "lazy-mcp@latest", "npx", "-y", "chrome-devtools-mcp@latest"] },
    "gitlab": { "command": ["npx", "lazy-mcp@latest", "npx", "mcp-remote@latest", "https://..."] },
    "grepai": { "command": ["npx", "lazy-mcp@latest", "grepai", "mcp-serve"] },
    "context7": { "command": ["npx", "-y", "@upstash/context7-mcp"] },
    "perplexity": { "command": ["npx", "-y", "@perplexity-ai/mcp-server"] }
  }
}

After (Consolidated into 1 multi-server proxy):

{
  "mcp": {
    "lazy-mcp": {
      "type": "local",
      "command": ["npx", "lazy-mcp@latest", "--config", "~/.config/lazy-mcp/servers.json"],
      "enabled": true
    }
  }
}

Where ~/.config/lazy-mcp/servers.json contains all 5 servers:

{
  "mode": "multi-server",
  "servers": [
    { "name": "chrome-devtools", "description": "Chrome DevTools automation", "type": "local", "command": ["npx", "-y", "chrome-devtools-mcp@latest"] },
    { "name": "gitlab", "description": "GitLab API integration", "type": "local", "command": ["npx", "mcp-remote@latest", "https://..."] },
    { "name": "grepai", "description": "Search codebase", "type": "local", "command": ["grepai", "mcp-serve"] },
    { "name": "context7", "description": "Library documentation", "type": "local", "command": ["npx", "-y", "@upstash/context7-mcp"] },
    { "name": "perplexity", "description": "Web search", "type": "local", "command": ["npx", "-y", "@perplexity-ai/mcp-server"] }
  ]
}

Result: ~90% context reduction (from ~16K to ~1.5K tokens initially)

Single-Server Mode (Legacy)

{
  "mcp": {
    "gitlab": {
      "command": ["npx", "lazy-mcp@latest", "npx", "mcp-remote", "https://gitlab.com/api/v4/mcp"]
    }
  }
}

Example

# Original local server with many tools
python my_server.py
# Exposes: tool1, tool2, tool3, ..., tool100 (uses 100x context tokens)

# Through lazy proxy - local
npx lazy-mcp@latest python my_server.py  
# Exposes: list_commands, describe_commands, invoke_command (uses 3x context tokens)

# Original remote server
curl http://localhost:3000/mcp -d '{"method":"tools/list"}'
# Returns: tool1, tool2, tool3, ..., tool100 (uses 100x context when loaded)

# Through lazy proxy - remote  
npx lazy-mcp@latest http://localhost:3000/mcp
# Exposes: list_commands, describe_commands, invoke_command (uses 3x context tokens)

Development

npm install
npm run build
npm run dev -- http://localhost:3000/mcp

Publishing New Versions

For Maintainers

1. Update version number:

   npm version patch  # for bug fixes
   npm version minor  # for new features
   npm version major  # for breaking changes

2. Build and test:

   npm run build
   npm test  # if tests exist

3. Commit changes:

   git add .
   git commit -m "Release v1.x.x"
   git push

4. Login to npm (first time only):

   npm login

5. Publish to npm:

   npm publish

6. Create git tag:

   git tag v1.x.x
   git push --tags

Configuration Reference

Server Configuration Fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | ✅ | Unique server identifier | | description | string | ✅ | Human-readable description | | type | "local" | "remote" | ✅ | Server connection type | | command | string[] | string | For local | Command to execute (array format recommended) | | args | string[] | Optional | Arguments (only if command is string) | | url | string | For remote | HTTP/HTTPS URL | | headers | object | Optional | HTTP headers for remote servers | | env | object | Optional | Environment variables (supports ${VAR} expansion) | | enabled | boolean | Optional | Enable/disable server (default: true) | | examples | object[] | Optional | Usage examples shown in list_servers output | | tags | string[] | Optional | Capability tags for filtering (e.g. "api", "browser") |

Command Format

Recommended (OpenCode-compatible):

{
  "command": ["npx", "-y", "my-mcp-server", "--port", "3000"]
}

Legacy (still supported):

{
  "command": "npx",
  "args": ["-y", "my-mcp-server", "--port", "3000"]
}

Environment Variables

Use ${VAR_NAME} to reference environment variables:

{
  "env": {
    "API_KEY": "${MY_API_KEY}",
    "DEBUG": "true"
  },
  "headers": {
    "Authorization": "Bearer ${AUTH_TOKEN}"
  }
}

Health Monitoring

lazy-mcp includes a background health monitor that probes all servers on startup and periodically. This means list_servers returns accurate healthy and error fields from the very first call, without needing to trigger discovery manually.

Successful probes also populate the discovery cache, so the first list_commands call for a healthy server returns instantly from cache.

Top-level configuration (in servers.json):

| Field | Type | Default | Description | |-------|------|---------|-------------| | healthMonitor.enabled | boolean | true | Enable/disable background health monitoring | | healthMonitor.interval | number | 30000 | Interval between health checks (ms) | | healthMonitor.timeout | number | 10000 | Timeout per server probe (ms) |

To disable:

{
  "mode": "multi-server",
  "servers": [...],
  "healthMonitor": { "enabled": false }
}

Config Reload (SIGHUP)

In multi-server mode, you can reload the configuration without restarting the process by sending a SIGHUP signal:

kill -HUP $(pgrep -f lazy-mcp)

This will:

• Re-read and validate the config file
• Add newly configured servers (lazy connection on first use)
• Remove servers no longer in config (closes connections)
• Reconnect servers whose config changed (updated URL, env, etc.)
• Preserve unchanged servers (keeps existing connections and caches)
• Restart the health monitor and probe all servers

If the new config is invalid, the reload is rejected and the current config continues running. All reload activity is logged to stderr.

Note: SIGHUP is not available on Windows. Single-server mode does not support config reload (no config file).

Benefits

• 90%+ context reduction - From ~16K to ~1.5K tokens initially
• Progressive tool discovery - Only load schemas when needed
• Multi-server aggregation - Manage multiple MCP servers in one config
• Batch discovery - Discover multiple servers efficiently
• Scales to hundreds of commands without context bloat
• Flexible configuration - Enable/disable servers on demand
• Environment variable support - Secure credential management
• Both local and remote - Support for subprocess and HTTP servers
• Health monitoring - Background probes detect broken servers before you hit them

Documentation

• CHANGELOG.md - Version history and release notes
• AGENTS.md - Development guide for AI coding agents (build commands, code style, testing patterns)
• doc/ARCHITECTURE.md - Architecture overview and design patterns
• doc/CONTRIBUTING.md - Contributing guide with common development tasks
• Configuration Reference - Server configuration options (above)