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. does it as a single Go binary with a local SQLite catalog. No containers, no API keys for the tool layer, no infrastructure.
local-first MCP discovery runtime for agents — search before invoke, reduce prompt bloat, and route to local MCP tools
Estrellas
39
Herramientas
—
Disponibilidad
—
lazy-tool
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
llama-3.1-8b-instant, 20 repeats per task. Methodology
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):
curl -sSfL https://raw.githubusercontent.com/rpgeeganage/lazy-tool/main/install.sh | INSTALL_DIR=/usr/local/bin 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
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
tui
Launch the interactive terminal UI
pin add|remove|list
Manage favorite capabilities (boosted in search)
catalog export|import|set-summary
Catalog management and manual summary overrides
cache-clear
Clear the response cache
version
Print version and git commit
All commands accept --config <path> or read from LAZY_TOOL_CONFIG.
server:
mcp:
transport: stdio # stdio | http
mode: search # search | direct | hybrid
host: "" # for HTTP transport
port: 8080 # for HTTP transport
Search tuning
search:
lexical_only: false
anthropic_tool_refs: false # adds anthropic.suggested_tool_use per hit
aliases:
k8s: "kubernetes cluster management"
scoring:
exact_canonical: 10 # exact match on proxy_tool_name
exact_name: 8 # exact match on original tool name
substring: 2 # substring match in name/summary/tags
vector_multiplier: 6 # semantic similarity weight
user_summary: 0.25 # boost for manually edited summaries
favorite: 0.2 # boost for pinned capabilities
invocation_boost: 0.5 # boost for previously invoked tools (learning signal)
Response cache
cache:
enabled: false # opt-in
max_entries: 500 # LRU eviction when full
ttl_seconds: 300 # 5 min default
exclude_sources: # sources that should never be cached
- mutation-heavy-source
Search algorithm
lazy-tool uses hybrid retrieval combining lexical and optional vector search.
query("echo")
→ Tokenize
→ [Optional] Generate query embedding
→ Lexical candidates: exact name → FTS5 BM25 → substring fallback
→ Vector candidates: cosine similarity (top N)
→ Merge + deduplicate
→ Score: exact match (10) + name match (8) + substring (2) + vector (6) + history + favorites
→ Rank, normalize [0,1], return with scores and why_matched
Every result includes why_matched explaining which signals contributed. Pass --explain-scores for full numeric breakdown.
Reliability features
Circuit breaker
Per-source circuit breaker protects against cascading failures from unhealthy upstreams.
Closed ──[max_failures]──▶ Open ──[cooldown]──▶ Half-Open
▲ │
└──────────[success]─────────────────────────────┘
HTTP session reuse
One MCP session per source, kept until idle timeout or error. Reduces handshake overhead for frequently called sources.
Passthrough fallback
Sources with fallback: passthrough return their full catalog when search returns zero results — a safety net that prevents the agent from being completely blind.
Response cache
When enabled, lazy-tool caches upstream responses in memory (LRU + TTL). Keyed by SHA-256 of tool name + input arguments. Per-source exclusion for mutation-heavy tools. Cache hits visible in trace logs and web UI.
xychart-beta
title "No-tool baseline: average input tokens"
x-axis ["Direct MCP", "lazy-tool"]
y-axis "Tokens" 0 --> 1800
bar [1701, 915]
xychart-beta
title "No-tool baseline: average latency (seconds)"
x-axis ["Direct MCP", "lazy-tool"]
y-axis "Seconds" 0 --> 0.3
bar [0.232, 0.158]
Discovery reliability
Task
Result
search_tools_smoke
20/20
search_tools_resource
18/20
search_tools_prompt
16/20
Multi-provider suite
Tests Groq, Anthropic, and OpenAI across all three modes (baseline, search, direct). Routed tasks verify end-to-end: search, invoke, and response validation.
make bench-strong # full suite (auto-detects API keys)
make bench-strong-test # unit tests (no API keys needed)
Weak-model (Ollama) suite
Tests local models (qwen2.5:3b, llama3.2:3b, phi3:mini, gemma2:2b) to prove search mode helps small models. Three tiers: basic tool-calling, search navigation, and deterministic search quality.
make bench-weak # full suite (needs Ollama)
make bench-weak-test # unit tests (no Ollama needed)
make bench-weak-validate # validate golden data
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Preguntas
¿Cómo instalo Lazy Tool?
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
¿Lazy Tool necesita una clave de API?
Este registro no indica ninguna variable de entorno obligatoria.
¿Qué transporte usa Lazy Tool?
Lazy Tool se ejecuta localmente por stdio.
¿Cuándo se comprobó Lazy Tool por última vez?
Última comprobación: 2026-10-28. local-first MCP discovery runtime for agents — search before invoke, reduce prompt bloat, and route to local MCP tools