lazy-tool

The more MCP servers you connect, the more tool schemas get dumped into every prompt. The model reads all of them, picks the wrong one more often, and you pay for every token. This is a known problem — the pattern that solves it (search before invoke) is well-established.

Most implementations of that pattern require a Python stack, a vector database, Docker, or a cloud service. lazy-tool does it as a single Go binary with a local SQLite catalog. No containers, no API keys for the tool layer, no infrastructure.

make build → import --write → reindex → serve

That's it. One binary, reads your existing IDE config, indexes everything locally, serves as an MCP endpoint.

| | Direct MCP | Through lazy-tool | |---|---:|---:| | Input tokens per turn | 1,701 | 915 (−46%) | | Latency per turn | 0.232s | 0.158s (−32%) | | Tools in agent context | 47 | 5 |

<sup>llama-3.1-8b-instant, 20 repeats per task. <a href="benchmark/README.md">Methodology</a></sup>

Where it fits

Several projects address MCP tool sprawl in different ways: RAG-MCP (Python + vector DB), MetaMCP (Docker), AWS AgentCore Gateway (managed cloud), and Claude Code's built-in tool search (client-side, Claude-only).

lazy-tool occupies a specific niche: local-first, zero-dependency, single binary.

No infrastructure. One Go binary, local SQLite. No Docker, no vector DB service, no cloud account.
IDE auto-import. Reads your Claude Desktop, Cursor, or VS Code MCP config. No manual YAML unless you want it.
Three modes in one tool. Direct mode (transparent proxy) for simple setups and smaller models, search mode (5 meta-tools) for large catalogs with strong models, hybrid for both. Switch with a flag.
Provider-agnostic. Not tied to Anthropic, OpenAI, or any specific client. Anything that speaks MCP over stdio or HTTP.
Reliability built in. Circuit breaking, caching, session reuse, and tracing handled at the proxy layer.

If you're already inside Claude Code and only use Claude, the built-in tool search may cover your needs. If you want something that works across providers, runs locally without dependencies, and aggregates multiple MCP servers — that's the space lazy-tool is in.

Install

Quick install (pre-built binary)

curl -sSfL https://raw.githubusercontent.com/rpgeeganage/lazy-tool/main/install.sh | sh

Override the install directory (default ./bin):

INSTALL_DIR=/usr/local/bin curl -sSfL https://raw.githubusercontent.com/rpgeeganage/lazy-tool/main/install.sh | sh

Go install

go install github.com/rpgeeganage/lazy-tool/cmd/lazy-tool@latest

Build from source

Requires Go 1.25+.

make build            # development build → bin/lazy-tool
make build-release    # optimized, stripped, version-stamped

Get started

If you already have MCP servers in Claude Desktop, Cursor, or VS Code:

./lazy-tool import --write   # reads your IDE config, generates lazy-tool config
./lazy-tool reindex          # indexes every tool, prompt, and resource
./lazy-tool serve            # agent connects here instead of directly to MCP servers

Point your agent at lazy-tool serve. It searches for tools instead of receiving them all in context.

No IDE config? Write a YAML file manually — see Configuration.

When to use which mode

Direct mode — every cataloged tool is exposed by name. The agent sees real schemas, lazy-tool routes transparently. Best for smaller/cheaper models (Haiku, GPT-4.1-mini, local Ollama) that struggle with multi-step reasoning. They get a simple tool list and call tools directly — one step, no search overhead. Also good for strong models that benefit from single-endpoint aggregation, circuit breaking, and caching.
Search mode (default) — the agent sees 5 meta-tools and discovers capabilities through search. Best for strong models (Claude, GPT-4, Llama 70B+) working with large tool catalogs (50+ tools) where dumping every schema into context wastes tokens and degrades selection accuracy. Requires the model to handle a two-step search→invoke pattern.
Hybrid mode — both search and direct tools available. Useful for gradual migration or mixed workloads.

lazy-tool serve                  # search (default)
lazy-tool serve --mode direct    # direct
lazy-tool serve --mode hybrid    # both

How it works

1. You configure MCP sources (or auto-import from your IDE)
2. lazy-tool reindex fetches every tool, prompt, and resource
3. The catalog is stored locally in SQLite with full-text search
4. Agents connect to lazy-tool via stdio or HTTP
5. The agent searches → finds → invokes — lazy-tool proxies to the real upstream

sequenceDiagram
    participant Agent
    participant LazyTool
    participant Catalog
    participant Upstream MCP

    Agent->>LazyTool: search_tools("echo")
    LazyTool->>Catalog: lexical + optional vector search
    Catalog-->>LazyTool: ranked results with scores
    LazyTool-->>Agent: proxy_tool_name + input example + next step

    Agent->>LazyTool: invoke_proxy_tool(name, input)
    LazyTool->>Upstream MCP: tools/call (original name)
    Upstream MCP-->>LazyTool: result
    LazyTool-->>Agent: response

The agent sees 5 tools regardless of how many exist upstream:

| Tool | Purpose | |---|---| | search_tools | Find capabilities by keyword or description | | inspect_capability | Get full schema before calling | | invoke_proxy_tool | Call an upstream tool through the proxy | | get_proxy_prompt | Fetch an upstream prompt | | read_proxy_resource | Read an upstream resource |

Reference

<details> <summary><strong>Table of contents</strong> (click to expand)</summary>

Install
Detailed setup
Auto-import from IDE configs
CLI reference
Configuration
Search algorithm
Reliability features
Response cache
Web UI and TUI
Benchmarks
Current limitations
Documentation map
Contributing

</details>

Detailed setup

Prerequisites

Go 1.25+
At least one local MCP server or gateway running

1. Build

make build
# or: go build -o bin/lazy-tool ./cmd/lazy-tool

2. Configure

Option A: Auto-import from your IDE (recommended)

# Discovers MCP servers from Claude Desktop, Cursor, and VS Code
./bin/lazy-tool import --write
export LAZY_TOOL_CONFIG=~/.lazy-tool/config.yaml

Option B: Write config manually

cp configs/example.yaml my-config.yaml
export LAZY_TOOL_CONFIG=$PWD/my-config.yaml

Minimal config:

app:
  name: my-tools

storage:
  sqlite_path: ./data/lazy-tool.db

sources:
  - id: my-gateway
    type: gateway
    transport: http
    url: http://localhost:8811/mcp

  - id: my-stdio-server
    type: server
    transport: stdio
    command: npx
    args: ["-y", "@your-scope/your-server"]
    env:
      API_KEY: "your-key"

3. Index the catalog

./bin/lazy-tool reindex
./bin/lazy-tool sources --status

4. Search

./bin/lazy-tool search "echo" --limit 5
./bin/lazy-tool search "file management" --explain-scores

5. Serve as MCP

# Search mode (default): 5 meta-tools, search-first workflow
./bin/lazy-tool serve

# Direct mode: all cataloged tools exposed as first-class MCP tools
./bin/lazy-tool serve --mode direct

# HTTP transport: serve over HTTP instead of stdio
./bin/lazy-tool serve --mode direct --transport http --addr :8080

Point your agent or IDE at lazy-tool serve as an MCP server. In HTTP mode, connect Claude Desktop to http://localhost:8080/mcp.

6. Optional UIs

./bin/lazy-tool web --addr 127.0.0.1:8765   # browser UI
./bin/lazy-tool tui                           # terminal UI

Auto-import from IDE configs

lazy-tool can automatically discover MCP server configurations from Claude Desktop, Cursor, and VS Code — no manual YAML writing needed.

# Preview what would be imported (prints YAML to stdout)
lazy-tool import

# Import from a specific IDE
lazy-tool import --from claude
lazy-tool import --from cursor
lazy-tool import --from vscode

# Write config directly
lazy-tool import --write
lazy-tool import --write --output my-config.yaml

Supported config file locations:

Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), %APPDATA%\Claude\claude_desktop_config.json (Windows)
Cursor: ~/.cursor/mcp.json
VS Code: ~/.vscode/mcp.json

CLI reference

| Command | Description | |---|---| | serve | Run as MCP server (stdio or HTTP) with mode selection | | search <query> | Search the catalog from CLI (JSON output) | | reindex | Fetch upstream capabilities and rebuild the local catalog | | inspect <proxy_tool_name> | Show full details for one indexed capability | | import | Auto-discover MCP servers from Claude Desktop, Cursor, VS Code | | health | Verify config and report basic status | | sources | List configured MCP sources | | web | Launch the browser-based UI

Lazy Tool

Install / Use

README