lazy-mcp

npx for MCP servers — install the catalog once, pay the context cost only for what you actually load.

Crates.io License: MIT

The Problem

Adding an MCP server to your agent is a one-way door. Every server you add — Supabase, Sentry, Playwright, Betterstack — dumps all of its tool definitions into context permanently, whether you use them once a session or never. Want to add one mid-session? Restart and lose your context. There's no lazy loading, no unloading, no cost visibility. You're paying rent on tools you're not using, every single turn.

lazy-mcp is the single MCP server you point your client at instead of N real ones — it shows you a one-line catalog, loads real tools only when an agent asks for them, and lets you hot-swap servers mid-session without losing your conversation.

	Without lazy-mcp	With lazy-mcp
Tools in context at session start	40+ (every configured server)	4 (`list_servers`, `load_server`, `unload_server`, `server_status`)
Add a new server mid-session	Restart client, lose context	`load_server("name")`, keep going
Know what a server costs you	No visibility	`server_status` shows per-server token estimate
Idle server you forgot about	Sits in context forever	Auto-unloads after idle timeout (coming soon)

Demo

(Demo GIF showing list_servers -> load_server("playwright") -> tool call -> unload_server goes here)

Install

cargo install lazy-mcp-proxy

Then, configure your Claude Desktop or Claude Code client to point to lazy-mcp:

{
  "mcpServers": {
    "lazy-mcp": {
      "command": "lazy-mcp",
      "args": ["--config", "/path/to/your/config.toml"]
    }
  }
}

Quickstart Config

Create a config.toml file to define your server catalog. You can define as many servers as you want; they cost zero context tokens until loaded.

[[servers]]
name = "supabase"
description = "Query and manage Supabase projects (tables, RLS, storage, auth)"
command = "npx"
args = ["-y", "@supabase/mcp-server-supabase"]
env = { SUPABASE_ACCESS_TOKEN = "${SUPABASE_ACCESS_TOKEN}" }
auto_unload_after_idle_secs = 600

[[servers]]
name = "playwright"
description = "Browser automation: navigate, click, screenshot"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-playwright"]

How it works

lazy-mcp acts as a transparent proxy. When it starts, it advertises only its meta-tools to your client. When you ask it to load a server, it spawns that server as a child process, fetches its tool list, namespaces them (e.g. playwright.navigate), and fires a notifications/tools/list_changed event. Your client re-fetches the tool list and instantly sees the new tools, mid-session.

Comparison to Alternatives

There are several other projects in this space, but lazy-mcp is the only one offering a full enterprise-grade feature set:

Feature	GitLab lazy-mcp	mcp-lazy (npm)	voicetreelab/lazy-mcp	lazy-mcp-preload	lazy-mcp 0.2
Basic lazy load/unload	✅	✅	✅	✅	✅
Config CLI rewriting	❌	✅	❌	❌	✅ (`lazy-mcp add`)
Category browsing	❌	❌	✅	❌	✅
Warm preloading	❌	❌	❌	✅	✅
Shared warm daemon	❌	❌	❌	❌	✅ (Share servers across IDEs)
Full protocol proxy	❌	❌	❌	❌	✅ (Resources & Prompts)
Real tokenizer costs	❌	❌	❌	❌	✅ (tiktoken-rs cl100k)
Live Web Dashboard	❌	❌	❌	❌	✅ (Port 4124)
Adaptive Eviction	❌	❌	❌	❌	✅ (`max_total_tokens`)
Safety dry-run	❌	❌	❌	❌	✅ (Secret redaction)
Permission Hooks	❌	❌	❌	❌	✅
Config merging	❌	❌	❌	❌	✅ (`conf.d/` dir support)

Meta-Tools Reference

Tool	Description
`list_servers`	Returns the catalog of available servers and their load status.
`load_server(name)`	Spawns the real MCP server and merges its tools into the client's context.
`unload_server(name)`	Tears down the child connection and removes its tools from context.
`server_status`	Shows uptime and real tiktoken token footprint for each loaded server.
`browse_category(path)`	Navigate large server lists hierarchically.

Dashboard & Daemon Mode

Instead of running separate instances for Claude Desktop, Claude Code, and Cursor, start the lazy-mcp daemon:

lazy-mcp daemon

This runs a shared daemon on 127.0.0.1:4123 and a live web dashboard on http://127.0.0.1:4124. Your clients automatically act as thin proxies, sharing the warm server pool to save memory and tokens!

Roadmap

Planned for future releases:

Semantic auto-loading (automatically loading a server based on intent).
Remote/HTTP transport (SSE/WebSocket proxying).
OAuth 2.0 + PKCE for remote servers.

Contributing

See CONTRIBUTING.md for details. Good first issue: Add a popular MCP server to our config.example.toml catalog! It requires zero Rust knowledge and helps everyone.

License

MIT License.

Lazy MCP