lazy

Lazy MCP exposes a minimal, on-demand gateway for MCP tools. It starts with two meta tools that let you explore a hierarchical catalog of available MCP tools and categories, and then transparently lazy-loads the actual tool servers only when a tool is requested. This keeps your agent’s context window lean by avoiding loading tools you don’t yet need. The core capabilities are: get_tools_in_category(path) to browse the tree of categories and tools, and execute_tool(tool_path, arguments) to run a specific tool by its hierarchical path. As you navigate deeper (for example, coding_tools.serena.find_symbol), Lazy MCP proxies the request to the corresponding tool server (e.g., Serena) and returns the result. This design enables on-demand loading and centralized permission hooks for sensitive tools via Claude Code or token-based hooks, while preserving a unified interface for tool discovery and execution.

Prerequisites:

• Access to a container runtime (Docker) or a compatible runtime for the chosen deployment method.
• If you want to run locally without Docker, you may alternatively run the prebuilt binary directly if available in your environment.

Installation steps:

1. Clone the repository (or obtain the Lazy MCP distribution): git clone https://github.com/voicetreelab/lazy-mcp.git cd lazy-mcp

2. Build or pull the runtime image (choose one):

   • Docker (recommended if a prebuilt image is published): docker pull voicetreelab/lazy-mcp
   • Local binary (if you have the build artifacts): make build

3. Prepare configuration:

   • Create a config.json at the project root or point the runtime to your config. The config defines mcpServers and the hierarchical structure to expose.
   • Example (minimal): { "servers": { "lazy-mcp": { "root": "./testdata/mcp_hierarchy" } } }

4. Run the service:

   • Docker: docker run -i -v $(pwd)/config.json:/config.json -e LAZY_MCP_CONFIG=/config.json voicetreelab/lazy-mcp
   • Local binary (if you built one): ./build/mcp-proxy --config config.json

5. Verify installation:

   • Access the CLI help or health endpoint as described in the repository docs, for example: ./build/mcp-proxy --help

6. Integrate with Claude Code (optional):

   • Add the mcp-proxy to Claude Code as a transport and point it to your running proxy, following the repository’s guidance for Claude Code integration.

Tips and considerations:

• Lazy loading: Tools are loaded on demand; ensure your tool servers are reachable by the proxy when an execute_tool call is made for the first time.
• Permissions: You can implement permission checks via Claude Code hooks or token-based hooks. The default flow routes all tool calls through execute_tool, so configure hooks to filter or prompt for sensitive actions.
• Hierarchy and discovery: Use get_tools_in_category("") to discover top-level categories, then drill down with further category paths (e.g., "coding_tools"). The tool paths are dot-separated strings (e.g., coding_tools.serena.find_symbol).
• Environment variables: You can expose configuration or sensitive tool lists via environment variables in conjunction with your deployment method (e.g., LAZY_MCP_CONFIG, LAZY_MCP_SENSITIVE_TOOLS, LAZY_MCP_DENIED_TOOLS).
• Troubleshooting: If a tool does not load on first invocation, check the target tool server’s availability, the network path from the proxy, and that the tool path matches the registered hierarchy (category/tool names).
• OpenCode and hooks: If using OpenCode or native hooks, you can add checks to log or warn about sensitive actions before execution. See the examples in the README for setting up hooks and environment-based tool lists.