mcp-lazy

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

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.

mcp-lazy 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 mcp-lazy	With mcp-lazy
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.

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 estimated token footprint for each loaded server.

Supported Servers

You can add any standard MCP server to your catalog. See config.example.toml in this repo for a comprehensive list covering:

• Dev tooling: filesystem, git, github, fetch
• Data/infra: supabase, postgres, sqlite, sentry, betterstack
• Browser/automation: playwright, puppeteer
• Productivity/comms: slack, google-drive, notion, linear
• Search/knowledge: brave-search, memory

Comparison to Alternatives

Currently, developers work around client limitations by writing one-off bash scripts or curl wrappers that expose temporary endpoints. This creates unmaintainable glue code, lacks proper child-process lifecycle management, and offers no native namespacing. lazy-mcp replaces this hack with real, reusable infrastructure: standard stdio transport, proper LRU eviction (roadmap), and isolated namespacing.

Roadmap

Non-goals for v1, planned for future releases:

• Semantic auto-loading (automatically loading a server based on intent).
• Remote/HTTP transport (SSE/WebSocket proxying).
• Interactive Dashboard for monitoring server usage.

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.