lazy-mcp

v2.3.1

Published

4 days ago

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

Downloads

6,247

0High
0Medium
0Low

dgruzd

mcp mcp-server model-context-protocol proxy lazy-loading ai-tools llm

Lazy MCP Proxy

Pipeline Status

A client-agnostic proxy 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. It works with any MCP client — Claude Desktop, OpenCode, Cursor, VS Code, and more.

Features

Client-Agnostic: Works with any MCP client — Claude Desktop, OpenCode, Cursor, VS Code, and any other MCP-compatible tool. Unlike client-specific solutions, lazy-mcp works everywhere you do.
Multi-Server Aggregation: 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
Streamable HTTP Transport: Run as an HTTP server — expose lazy-mcp over the network so remote clients can connect via POST /mcp

How It Works

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

Homebrew (macOS and Linux, no runtime dependencies):

brew tap gitlab-org/lazy-mcp https://gitlab.com/gitlab-org/ai/lazy-mcp
brew install lazy-mcp

Cargo (if you have Rust installed, no Node.js required):

cargo install lazy-mcp

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

Or install globally (locks to specific version):

npm install -g lazy-mcp

Docker / Podman:

docker build -t lazy-mcp .
docker compose up

The image compiles the TypeScript CLI during docker build, so this works from a clean checkout without a prebuilt dist/ directory.

Or with Podman:

podman build -t lazy-mcp .
podman compose up

This runs lazy-mcp in HTTP mode on port 8080 with config mounted from ~/.config/lazy-mcp/servers.json. See docker-compose.yml for configuration options.

Usage

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 MCP server",
      "url": "https://gitlab.com/api/v4/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

Streamable HTTP Transport

By default, lazy-mcp communicates over stdio (standard MCP transport). You can also run it as an HTTP server using the Streamable HTTP transport, allowing remote clients to connect over the network:

Via config file — add a transport block to servers.json:

{
  "servers": [
    { "name": "my-server", "description": "My MCP server", "command": ["python", "server.py"] }
  ],
  "transport": {
    "type": "http",
    "port": 3000,
    "host": "localhost",
    "path": "/mcp",
    "authToken": "${MY_API_KEY}"
  }
}

Via CLI flags (override config values):

# Start HTTP server on port 3000
lazy-mcp --config servers.json --transport http --port 3000

# With custom host, path, and auth
lazy-mcp --config servers.json --transport http --port 3000 --host 127.0.0.1 --path /mcp --auth-token "my-secret"

Security note: --host 0.0.0.0 exposes the HTTP server on all network interfaces. Use it only inside Docker or trusted networks.

Reverse proxy note: The default Origin check uses the scheme visible to lazy-mcp's own socket plus the incoming Host header. If you run lazy-mcp behind a TLS-terminating reverse proxy, the backend hop is usually plain HTTP, so the implicit same-origin shortcut may reject public HTTPS origins. In that setup, configure transport.allowedOrigins explicitly. If your proxy preserves the public Host header, configure transport.allowedHosts too.
Example:
{
  "transport": {
    "type": "http",
    "host": "127.0.0.1",
    "port": 8080,
    "path": "/mcp",
    "allowedHosts": ["mcp.example.com"],
    "allowedOrigins": ["https://mcp.example.com"]
  }
}
lazy-mcp intentionally does not trust Forwarded / X-Forwarded-* headers by default. If proxy-aware origin reconstruction is ever added, it should be behind an explicit trusted-proxy setting.

Via environment variables (lowest precedence):

LAZY_MCP_TRANSPORT=http LAZY_MCP_PORT=3000 LAZY_MCP_AUTH_TOKEN=my-secret lazy-mcp

Precedence: CLI flags > config file > environment variables > defaults.

Once running, clients connect as a remote MCP server:

# Quick test with curl
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ${MY_API_KEY}" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Note: Server-initiated notifications via GET/SSE are not supported in stateless mode. Use POST for all requests.

Integration (Claude Desktop, OpenCode, Cursor, VS Code, and more)

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

HTTP mode — for clients that support remote MCP servers:

Start lazy-mcp in HTTP mode (e.g. lazy-mcp --config servers.json --transport http --port 3000), then configure your client:

{
  "mcp": {
    "lazy-mcp": {
      "type": "remote",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer ${LAZY_MCP_AUTH_TOKEN}"
      }
    }
  }
}

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)

Example

# Configure multiple MCP servers in servers.json, then:
npx lazy-mcp@latest --config ~/.config/lazy-mcp/servers.json
# Exposes: list_servers, list_commands, describe_commands, invoke_command (4 meta-tools)
# Instead of loading all tools from all servers upfront (~16K+ tokens),
# the agent discovers tools on-demand (~1.5K tokens initially)

Development

npm install
npm run build
npm test

Running from Local Source

Instead of npx lazy-mcp@latest (which downloads the published package), you can run directly from the cloned repo:

Without building — using ts-node (picks up source changes immediately):

npm run dev -- --config ~/.config/lazy-mcp/servers.json

After building — run the compiled output:

npm run build
node dist/cli.js --config ~/.config/lazy-mcp/servers.json
# or equivalently:
npm start -- --config ~/.config/lazy-mcp/servers.json

In an MCP client config — point directly at the local build:

{
  "mcp": {
    "lazy-mcp": {
      "command": "node",
      "args": ["/path/to/lazy-mcp/dist/cli.js", "--config", "~/.config/lazy-mcp/servers.json"]
    }
  }
}

Or with ts-node (no build needed, always reflects latest source):

{
  "mcp": {
    "lazy-mcp": {
      "command": "npx",
      "args": ["ts-node", "/path/to/lazy-mcp/src/cli.ts", "--config", "~/.config/lazy-mcp/servers.json"]
    }
  }
}

Releases

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

How It Works

CI analyzes all commits since the last tag using Conventional Commits
Determines the next version (feat → minor bump, fix/perf/chore/refactor/test → patch bump)
Updates package.json, CHANGELOG.md, VERSION, and RELEASE_NOTES.md
Commits those files as chore(release): X.Y.Z and pushes a vX.Y.Z tag
Creates a GitLab Release with the generated release notes
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

Four 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 | | CARGO_TOKEN | crates.io API token — publishes the crate to crates.io 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) |

`CARGO_TOKEN`

Creating the token (crates.io → Account Settings → API Tokens → New Token):

| Setting | Value | |---------|-------| | Token name | lazy-mcp-ci (or any name) | | Scopes | publish-new, publish-update |

Adding the variable:

| Setting | Value | |---------|-------| | Key | CARGO_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:

Agent calls invoke_command (or list_commands) on an OAuth-protected server
lazy-mcp returns an isError: true response with the authorization URL
Agent presents the URL to the user: "Open this URL to authorize Glean: https://..."
User opens the URL in a browser and completes authorization
Browser redirects to http://localhost:8947/callback — lazy-mcp captures the token
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}"
  }
}

Transport Configuration

Configure how lazy-mcp exposes its MCP endpoint. By default, it uses stdio (for subprocess-based clients). Set type: "http" to run as an HTTP server.

Top-level configuration (in servers.json):

| Field | Type | Default | Description | |-------|------|---------|-------------| | transport.type | "stdio" | "http" | "stdio" | Transport mode | | transport.port | number | 8080 | HTTP server port | | transport.host | string | "127.0.0.1" | HTTP server bind address. For TLS-terminating reverse proxies, keep localhost binding and configure allowedOrigins explicitly. | | transport.path | string | "/mcp" | MCP endpoint URL path | | transport.authToken | string | — | Bearer token for HTTP auth (supports ${VAR} expansion) | | transport.allowedOrigins | string[] | — | List of allowed Origin header values for request-origin validation / CSRF protection (e.g. ["https://example.com"]). Full origins including scheme and port. Recommended for TLS-terminating reverse-proxy deployments. Does not send CORS response headers. | | transport.allowedHosts | string[] | — | List of explicitly allowed host domains for DNS rebinding protection. If a reverse proxy preserves the public Host header, add that host here. | | transport.maxPayloadSize | number | 4194304 | Maximum request body size in bytes. Requests exceeding this limit return HTTP 413 |

CLI flags (override config values):

| Flag | Env Variable | Description | |------|-------------|-------------| | --transport | LAZY_MCP_TRANSPORT | Transport type (stdio or http) | | --port | LAZY_MCP_PORT | HTTP server port | | --host | LAZY_MCP_HOST | HTTP server bind address | | --path | LAZY_MCP_PATH | MCP endpoint URL path | | --auth-token | LAZY_MCP_AUTH_TOKEN | Bearer token for HTTP auth | | --request-timeout | LAZY_MCP_REQUEST_TIMEOUT | Request timeout in ms for server calls, including MCP handshake requests and remote response parsing (default: 10000) | | --max-payload-size | LAZY_MCP_MAX_PAYLOAD_SIZE | Maximum request body size in bytes (default: 4194304) |

When authToken is set, all HTTP requests must include Authorization: Bearer <token> — unauthenticated requests receive 401 Unauthorized.

Logging Configuration

lazy-mcp now emits structured logs to stderr (stdout remains reserved for MCP protocol traffic).

Top-level configuration (in servers.json):

| Field | Type | Default | Description | |-------|------|---------|-------------| | logging.level | "error" | "info" | "debug" | "info" | Minimum log level | | logging.format | "json" | "plain" | "json" | Log output format | | logging.dumpBodies | boolean | false | Enable debug request/response body dumps | | logging.maxBodyLogBytes | number | 8192 | Max body-dump size in bytes before truncation | | logging.redactKeys | string[] | — | Additional case-insensitive keys to redact (merged with built-in defaults) |

Built-in redaction includes common secret keys like authorization, token, access_token, refresh_token, client_secret, and headers.authorization.

Example:

{
  "servers": [
    {
      "name": "my-server",
      "description": "Example",
      "command": ["npx", "-y", "my-mcp-server"]
    }
  ],
  "logging": {
    "level": "debug",
    "format": "json",
    "dumpBodies": true,
    "maxBodyLogBytes": 4096,
    "redactKeys": ["my_custom_secret"]
  }
}

Typical access log event fields include:

client source (clientIp, optional forwardedFor)
request shape (httpMethod, path, mcpMethod, lazyTool)
downstream routing (downstreamServer, downstreamCommand)
outcome (status, reason, durationMs)

Health Monitoring

lazy-mcp includes a background health monitor that probes all servers periodically. The monitor is activity-driven: it sleeps on startup and only begins probing after the first user tool call (list_servers, list_commands, etc.). After a configurable idle timeout (default: 5 minutes) with no tool calls, the monitor goes back to sleep. This prevents OAuth-protected servers (e.g. GitLab via mcp-remote) from opening browser windows when no one is using the tools.

Successful probes populate the discovery cache, so subsequent list_commands calls return 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) | | healthMonitor.idleTimeout | number | 300000 | Stop probing after this much inactivity (ms). 0 = never sleep (legacy) | | requestTimeout | number | 10000 | Timeout for individual server requests. For remote HTTP servers, this includes waiting for headers, reading response bodies, and SSE response parsing. Override via --request-timeout or LAZY_MCP_REQUEST_TIMEOUT |

To disable health monitoring:

{
  "servers": [...],
  "healthMonitor": { "enabled": false }
}

To increase the request timeout (e.g. for slow remote servers):

{
  "servers": [...],
  "requestTimeout": 30000
}

Config Reload (SIGHUP)

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.

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
Streamable HTTP transport - Run as an HTTP server for remote client access
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
doc/requests/ - Bruno API collection for testing the Streamable HTTP transport. Open the doc/requests/ folder as a collection in Bruno, select the local or local-with-auth environment, and run requests against a locally running lazy-mcp --transport http instance.
Configuration Reference - Server configuration options (above)

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Lazy MCP Proxy

Table of Contents

Features

How It Works

Installation

Usage

Streamable HTTP Transport

Integration (Claude Desktop, OpenCode, Cursor, VS Code, and more)

Example

Development

Running from Local Source

Releases

How It Works

Required CI/CD Variables

GITLAB_RELEASE_TOKEN

NPM_TOKEN

PYPI_TOKEN

CARGO_TOKEN

Configuration Reference

Server Configuration Fields

OAuth 2.0 Authentication

Command Format

Environment Variables

Transport Configuration

Logging Configuration

Health Monitoring

Config Reload (SIGHUP)

Benefits

Documentation

`GITLAB_RELEASE_TOKEN`

`NPM_TOKEN`

`PYPI_TOKEN`

`CARGO_TOKEN`