Tool Search
MCP proxy server β 85-96% token savings via lazy tool loading & fuzzy search across 100+ MCP servers. npm i mcp-tool-search
Ask AI about Tool Search
Powered by Claude Β· Grounded in docs
I know everything about Tool Search. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
MCP Tool Search
Reduce MCP tool-definition context overhead by ~85β96%.
MCP Tool Search is a proxy server that replaces dozens of MCP tool schemas in your model's context window with just 4 lightweight tools. Instead of loading every tool definition upfront, the model searches for tools on-demand and calls them through the proxy.
Before: 50 tool schemas loaded β ~10,000 context tokens consumed every turn
After: 4 proxy tools loaded β ~600 context tokens (constant)
Problem
Every MCP server you add dumps its full tool schemas into the model's context window. With 5+ servers and 40+ tools, that's 8,000β20,000+ tokens of schema definitions the model must process on every single turn β even when it doesn't use any of them.
Solution
MCP Tool Search sits between your MCP client and your backend servers:
- Catalog Builder pre-scans all your MCP servers and snapshots their tool definitions to a local JSON file
- Proxy Server exposes only 4 tools β the model searches, inspects, and calls tools through the proxy
- Lazy Connections β backend servers are spawned on first use and kept alive for 5 minutes
MCP Client ββ MCP Tool Search Proxy ββ Backend MCP Servers
β (lazily spawned)
catalog.json Context7, GitHub, etc.
(pre-built snapshot)
The 4 Proxy Tools
| Tool | Purpose |
|---|---|
search_tools | Fuzzy-search across all backend tools by keyword or capability |
get_tool_schema | Retrieve the full input schema for a specific tool |
call_tool | Execute a tool on its backend server through the proxy |
list_servers | List all cataloged servers and their connection status |
Quick Start
npx mcp-tool-search --help
# Or: npm install -g mcp-tool-search && mcp-build-catalog && mcp-tool-search
Installation
Option A: npm (recommended)
npm install -g mcp-tool-search
Option B: From source
git clone https://github.com/KGT24k/mcp-tool-search.git
cd mcp-tool-search
npm install
npm run build
Setup
1. Configure backend servers
MCP Tool Search reads your MCP client's server configuration to discover backend tools. It uses the same .mcp.json format as Claude Code.
2. Build the tool catalog
# If installed globally:
mcp-build-catalog
# If from source:
npm run catalog
This connects to each configured MCP server, snapshots their tool definitions, and writes catalog.json. The proxy itself is automatically excluded from the catalog.
3. Add the proxy to your MCP client
Choose your client below for the correct configuration:
Claude Code
Add to your .mcp.json in the project root (or ~/.mcp.json for global config):
{
"mcpServers": {
"mcp-tool-search": {
"command": "npx",
"args": ["-y", "mcp-tool-search"]
}
}
}
Or if installed from source:
{
"mcpServers": {
"mcp-tool-search": {
"command": "node",
"args": ["/path/to/mcp-tool-search/dist/index.js"]
}
}
}
Claude Desktop
Add to your claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"mcp-tool-search": {
"command": "npx",
"args": ["-y", "mcp-tool-search"]
}
}
}
Cursor
Add to your Cursor MCP settings (.cursor/mcp.json in your project or global config):
{
"mcpServers": {
"mcp-tool-search": {
"command": "npx",
"args": ["-y", "mcp-tool-search"]
}
}
}
Windsurf
Add to your Windsurf MCP configuration (~/.codeium/windsurf/mcp_config.json):
{
"mcpServers": {
"mcp-tool-search": {
"command": "npx",
"args": ["-y", "mcp-tool-search"]
}
}
}
4. Disable direct backend servers
Remove or disable your other MCP server entries in .mcp.json β the proxy handles all tool calls to them now.
Environment Variables
| Variable | Default | Purpose |
|---|---|---|
MCP_TOOL_SEARCH_CATALOG | ./catalog.json | Path to the catalog file |
MCP_TOOL_SEARCH_METRICS | (none) | Path to write JSON metrics (for monitoring dashboards) |
Token Savings
The proxy's token footprint is constant β 4 tools regardless of how many backend servers exist.
| Backend Tools | Direct Tokens | Proxy Tokens | Savings |
|---|---|---|---|
| 10 | ~2,000 | ~600 | 70% |
| 25 | ~5,000 | ~600 | 88% |
| 50 | ~10,000 | ~600 | 94% |
| 100 | ~20,000 | ~600 | 97% |
| 200 | ~40,000 | ~600 | 99% |
See BENCHMARKS.md for detailed methodology and measurements.
Security
MCP Tool Search uses an allowlist-based environment filter when spawning backend servers. Only explicitly safe environment variables (PATH, HOME, NODE_PATH, etc.) are forwarded to child processes. API keys, tokens, and secrets from your shell environment are never leaked to backend servers unless explicitly configured in the catalog's per-server env block.
Additional security measures:
- Connection cap: Max 20 concurrent server connections (oldest idle connection evicted when limit reached)
- Connect timeout: 15-second timeout on server spawn
- Idle cleanup: Connections auto-close after 5 minutes of inactivity
- No shell execution: Server commands passed as arrays to
child_process.spawn(), never through shell interpretation - TypeScript strict mode: Full type safety with no
anycasts in core logic - Minimal dependencies: Only 2 runtime deps (
@modelcontextprotocol/sdk,zod)
Note:
catalog.jsonstores per-server env vars from your MCP config (including API tokens that backend servers need to function). Treat this file as sensitive β it is excluded from git (.gitignore) and npm publishing (.npmignore+"files"allowlist) by default. Do not share or commit it.
Trade-offs
- Latency: Each tool call requires a search + schema lookup step (~2 extra LLM turns for first use of a tool)
- Discovery: The model must search for tools instead of seeing them all upfront β minor overhead for small catalogs
- Connection startup: Servers are lazily spawned, so first calls to a new server have connection overhead
When to use the proxy
- Use it when you have 5+ MCP servers or 20+ total tools
- Use it when you need cross-client compatibility (Cursor, Windsurf, VS Code, etc.)
- Use it when you want to aggregate tools from multiple servers behind one endpoint
- Skip it when you have 1β2 servers with few tools
vs. Anthropic's Built-in Tool Search
Claude Code includes a built-in defer_loading mechanism for tool schema optimization. Here's how MCP Tool Search differs:
| Feature | MCP Tool Search | Anthropic defer_loading |
|---|---|---|
| Works with Cursor, Windsurf, VS Code | β | β Claude-only |
| Cross-server aggregation | β Single endpoint | β Per-server |
| Streamable HTTP transport | β Remote clients | β Stdio only |
| Fuzzy search with typo tolerance | β Levenshtein | Basic regex/BM25 |
| Pre-built catalog (offline) | β | β Runtime only |
If you only use Claude Code, Anthropic's built-in solution may be sufficient. If you use multiple MCP clients or need cross-server tool federation, MCP Tool Search fills that gap.
Compatibility
Tested with:
- Claude Code (primary target)
- Claude Desktop
- Cursor
- Windsurf
Should work with any MCP client that supports the stdio transport.
Project Structure
mcp-tool-search/
βββ src/
β βββ types.ts # Shared type definitions
β βββ catalog.ts # Catalog loader + fuzzy search engine
β βββ pool.ts # Lazy server connection pool with timeouts
β βββ index.ts # Main proxy MCP server
β βββ build-catalog.ts # Catalog builder CLI
βββ dist/ # Compiled JavaScript (after build)
βββ catalog.json # Generated tool catalog (git-ignored)
βββ package.json
βββ tsconfig.json
βββ README.md
Development
# Install dependencies
npm install
# Build TypeScript
npm run build
# Run tests
npm test
# Watch mode
npm run dev
# Rebuild catalog
npm run catalog
Contributing
Contributions are welcome! Here's how to get started:
- Fork the repository and clone your fork
- Install dependencies:
npm install - Build:
npm run build - Run tests:
npm test(all 81 tests must pass) - Make your changes on a feature branch
- Submit a PR with a clear description of what changed and why
Guidelines
- Follow the existing TypeScript style (strict mode, no
anyin core logic) - Add tests for new features or bug fixes
- Keep dependencies minimal -- any new runtime dependency needs strong justification
- Run
npm auditand ensure 0 vulnerabilities before submitting - Update documentation if your change affects the public API or setup process
Reporting Issues
Found a bug or have a feature request? Open an issue on GitHub.
For security vulnerabilities, please use GitHub Security Advisories instead of public issues.
Changelog
See CHANGELOG.md for a detailed history of all releases.
Security
Using many MCP servers? Audit your configs first.
Config Guard scans your .mcp.json for 20 types of security vulnerabilities β typosquatting, known CVEs, secret leaks, rug pulls, and more. Zero dependencies, fully offline.
pip install mcp-config-guard && config-guard
MCP Tool Search saves tokens. Config Guard saves you from CVEs.
License
MIT β Copyright (c) 2026 AEGIS Forge Team
