lazy-mcp 1.8.1

A proxy tool that converts normal MCP servers to use lazy-loading pattern with meta-tools

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
• Releases
  • How It Works
  • Required CI/CD Variables
    • GITLAB_RELEASE_TOKEN
    • NPM_TOKEN
    • PYPI_TOKEN
• Configuration Reference
  • Server Configuration Fields
  • OAuth 2.0 Authentication
  • 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
• 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
• Built-in OAuth 2.0 + PKCE: Authenticate with OAuth-protected remote servers without a browser — works in sandboxed agent environments
• 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. Response includes pid and config_file so an agent can fix broken config and reload via kill -HUP <pid>
• 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

If you have Python / uv (no Node.js required):

uvx lazy-mcp

If you have Node.js — use 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:

{
  "servers": [
    {
      "name": "chrome-devtools",
      "description": "Chrome DevTools automation",
      "command": ["npx", "-y", "chrome-devtools-mcp@latest"]
    },
    {
      "name": "gitlab",
      "description": "GitLab API integration",
      "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 with static token",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    },
    {
      "name": "glean",
      "description": "Glean enterprise search (OAuth)",
      "url": "https://your-company.glean.com/mcp/default"
    }
  ]
}

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:

{
  "servers": [
    { "name": "chrome-devtools", "description": "Chrome DevTools automation", "command": ["npx", "-y", "chrome-devtools-mcp@latest"] },
    { "name": "gitlab", "description": "GitLab API integration", "command": ["npx", "mcp-remote@latest", "https://..."] },
    { "name": "grepai", "description": "Search codebase", "command": ["grepai", "mcp-serve"] },
    { "name": "context7", "description": "Library documentation", "command": ["npx", "-y", "@upstash/context7-mcp"] },
    { "name": "perplexity", "description": "Web search", "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

Releases

Releases are fully automated via semantic-release on every push to main.

How It Works

1. CI analyzes all commits since the last tag using Conventional Commits
2. Determines the next version (feat → minor bump, fix/perf/chore/refactor/test → patch bump)
3. Updates package.json, CHANGELOG.md, VERSION, and RELEASE_NOTES.md
4. Commits those files as chore(release): X.Y.Z and pushes a vX.Y.Z tag
5. Creates a GitLab Release with the generated release notes
6. The vX.Y.Z tag triggers a separate pipeline that publishes the package to npm automatically

No manual version bumping or tagging needed — just merge to main with conventional commit messages.

Required CI/CD Variables

Three CI/CD variables must be configured (GitLab → Project → Settings → CI/CD → Variables):

Variable	Description
GITLAB_RELEASE_TOKEN	Project access token — pushes the release commit + tag to main and creates the GitLab Release
NPM_TOKEN	npm automation token — publishes the package to the npm registry on tag pipelines
PYPI_TOKEN	PyPI API token — publishes the package to PyPI on tag pipelines

GITLAB_RELEASE_TOKEN

Creating the token (GitLab → Project → Settings → Access Tokens):

Setting	Value
Token name	semantic-release-bot (or any name)
Role	Developer (push to a protected branch should be configured separately)
Scopes	api, write_repository

Adding the variable:

Setting	Value
Key	GITLAB_RELEASE_TOKEN
Masked	✅ Yes
Protected	❌ No (must be available on the unprotected main pipeline)

Note: If main is a protected branch with push restrictions, the token's bot user must be added to the "Allowed to push" list under GitLab → Project → Settings → Repository → Protected branches.

NPM_TOKEN

Creating the token (npmjs.com → Account → Access Tokens → Generate New Token):

Setting	Value
Token type	Automation (bypasses 2FA, suitable for CI)

Adding the variable:

Setting	Value
Key	NPM_TOKEN
Masked	✅ Yes
Protected	✅ Yes (only needed on tag pipelines, which are protected)

PYPI_TOKEN

Creating the token (pypi.org → Account Settings → API tokens → Add API token):

Setting	Value
Token name	lazy-mcp-ci (or any name)
Scope	Project: lazy-mcp (restrict to this project after first publish; use "Entire account" for the very first publish)

Adding the variable:

Setting	Value
Key	PYPI_TOKEN
Masked	✅ Yes
Protected	✅ Yes (only needed on tag pipelines, which are protected)

Configuration Reference

Server Configuration Fields

Field	Type	Required	Description
name	string	✅	Unique server identifier
description	string	✅	Human-readable description
type	"local" | "remote"	Optional	Inferred from url (remote) or command (local) if omitted
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	Static HTTP headers for remote servers
oauth	object	Optional	OAuth 2.0 config for remote servers (see below)
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")

OAuth 2.0 Authentication

lazy-mcp has built-in OAuth 2.0 + PKCE support for remote servers that require user authorization. It works without opening a browser automatically, making it suitable for sandboxed agent environments: when authentication is needed, lazy-mcp returns the authorization URL in the error message so the agent can present it to the user.

OAuth server endpoints are discovered automatically via RFC 8414 (/.well-known/oauth-authorization-server). Dynamic client registration (RFC 7591) is used when no clientId is provided.

Tokens are persisted to ~/.config/lazy-mcp/tokens.json (mode 0600) and refreshed automatically via refresh_token when available.

Minimal config (fully automatic — discovery + dynamic registration):

{
  "name": "glean",
  "description": "Glean enterprise search",
  "url": "https://your-company.glean.com/mcp/default",
  "oauth": {}
}

With a pre-registered client ID:

{
  "name": "glean",
  "description": "Glean enterprise search",
  "url": "https://your-company.glean.com/mcp/default",
  "oauth": {
    "clientId": "${GLEAN_CLIENT_ID}",
    "extraHeaders": { "X-Glean-Auth-Type": "OAUTH" }
  }
}

oauth object fields:

Field	Type	Default	Description
clientId	string	—	OAuth client ID. If omitted, dynamic registration (RFC 7591) is attempted
clientSecret	string	—	Client secret (omit for public-client / PKCE-only flows)
callbackPort	number	8947	Local port for the OAuth redirect callback server
extraHeaders	object	—	Additional headers added to every authenticated request (e.g. X-Glean-Auth-Type)

How it works:

1. Agent calls invoke_command (or list_commands) on an OAuth-protected server
2. lazy-mcp returns an isError: true response with the authorization URL
3. Agent presents the URL to the user: "Open this URL to authorize Glean: https://..."
4. User opens the URL in a browser and completes authorization
5. Browser redirects to http://localhost:8947/callback — lazy-mcp captures the token
6. Agent retries the original command — now succeeds transparently

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:

{
  "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)