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:

1. Catalog Builder pre-scans all your MCP servers and snapshots their tool definitions to a local JSON file
2. Proxy Server exposes only 4 tools — the model searches, inspects, and calls tools through the proxy
3. 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

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:

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"]
    }
  }
}

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"]
    }
  }
}

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"]
    }
  }
}

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

Token Savings

The proxy's token footprint is constant — 4 tools regardless of how many backend servers exist.

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 any casts in core logic
• Minimal dependencies: Only 2 runtime deps (@modelcontextprotocol/sdk, zod)

Note: catalog.json stores 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:

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:

1. Fork the repository and clone your fork
2. Install dependencies: npm install
3. Build: npm run build
4. Run tests: npm test (all 81 tests must pass)
5. Make your changes on a feature branch
6. Submit a PR with a clear description of what changed and why

Guidelines

• Follow the existing TypeScript style (strict mode, no any in core logic)
• Add tests for new features or bug fixes
• Keep dependencies minimal -- any new runtime dependency needs strong justification
• Run npm audit and 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