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 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:

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:

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 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.

Name		Name	Last commit message	Last commit date
Latest commit History 26 Commits
.github		.github
src		src
website		website
.gitignore		.gitignore
.npmignore		.npmignore
BENCHMARKS.md		BENCHMARKS.md
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
install.bat		install.bat
package-lock.json		package-lock.json
package.json		package.json
smithery.yaml		smithery.yaml
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

MCP Tool Search

Problem

Solution

The 4 Proxy Tools

Quick Start

Installation

Option A: npm (recommended)

Option B: From source

Setup

1. Configure backend servers

2. Build the tool catalog

3. Add the proxy to your MCP client

4. Disable direct backend servers

Environment Variables

Token Savings

Security

Trade-offs

When to use the proxy

vs. Anthropic's Built-in Tool Search

Compatibility

Project Structure

Development

Contributing

Guidelines

Reporting Issues

Changelog

Security

License

About

Topics

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages