lazy-mcp

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.

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.

Related MCP server: nimble

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:

Meta-Tools Reference

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.