datolabs-io/mcp-toolsearch-proxy

mcp-toolsearch-proxy lets a model use hundreds or thousands of MCP tools without loading them. On 500 tools, each
request carries 97% fewer tokens of tool definitions, a task costs about half as much, and the model reaches the right
tool nearly as often as with every tool loaded (benchmarks).
It is an MCP server that puts five tools in front of an MCP server with far too many
to list to a model, such as a gateway that aggregates dozens of servers:
| Tool | Does |
| searchtools | finds the tools that can do what a query describes, with the input schemas of the best few, for up to 5 queries at once; with the built-in model, in English, Lithuanian or any of 100 other languages |
| describetool | returns the full description and input schema of up to 10 tools |
| callreadtool | calls a tool the upstream marks read-only, and refuses any other |
| callreadtools | calls up to 10 read-only tools at once, in parallel, with a result for each (-max-batch-calls; 0 leaves it out) |
| callwritetool | calls any tool, for those that may create, change or delete something |
A catalog of a thousand tools costs a model over 100,000 tokens of tool definitions before it does anything, and many
clients cap how many tools they load anyway. Behind the proxy, the model sees five, in 1,735 tokens.
A call whose arguments do not fit the tool's input schema (a required property missing, a wrong type, a value outside
an enum) is refused before it reaches the upstream, with what is wrong and the schema, so the model can fix it at once.
The same goes for an unknown name that is clearly a typo of one tool, and for an upstream that answers invalid params.
Calls come in separate tools so that a client can tell them apart: callreadtool and callreadtools are marked
read-only and can be allowed to run without asking, while callwritetool is marked destructive and can keep asking
every time. Writes are never batched, so each keeps its own approval. A tool counts as
read-only only when the upstream server marks it so (readOnlyHint); unmarked tools are writes, and so are any the
operator lists in -write-tools. Allowing callreadtool allows every read-only tool of every server behind the
upstream, including servers added later; docs/clients.md says what that grant covers and how to set
up claude.ai and Claude Code.
text
client ──▶ gateway /mcp/search ──▶ mcp-toolsearch-proxy ──▶ gateway /mcp/all ──▶ MCP servers
## How it works
The proxy has no credentials. Each request it sends upstream carries the caller's Authorization header and nothing
else, so the upstream server (usually the same gateway, on another route) authenticates and authorizes the caller as
if they had come directly. Whatever the caller isn't allowed to see or call, the proxy can't see or call either.
Each caller gets their own catalog: the tools the upstream lists for that caller. It is kept for ten minutes, then
listed again in the background while the old one is still used, and it is looked up by a hash of the token. A claim
inside the token, such as sub, would be easier to key on but can't be trusted without verifying the token, so the
proxy doesn't use one.
Search combines two rankings. BM25 matches words in tool names, descriptions and parameters, with Lithuanian and