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 |
| 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 |
| returns the full description and input schema of up to 10 tools |
| calls a tool the upstream marks read-only, and refuses any other |
| calls up to 10 read-only tools at once, in parallel, with a result for each ( |
| 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: call_read_tool and call_read_tools are marked
read-only and can be allowed to run without asking, while call_write_tool 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 call_read_tool 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.
client ──▶ gateway /mcp/search ──▶ mcp-toolsearch-proxy ──▶ gateway /mcp/all ──▶ MCP serversThe 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 English endings stemmed and diacritics ignored. A multilingual embedding model, potion-multilingual-128M (MIT), matches by meaning. The model runs inside the proxy, in pure Go, without a GPU or an embedding service, and embedding a query takes microseconds. Without the model, search falls back to BM25 alone, which matches only words a tool's text shares with the query: it stems no endings but Lithuanian and English ones, and does not split Chinese or Japanese text into words.
The upstream server's own instructions still reach the model. The proxy answers each caller's handshake with its own
short guidance followed by the upstream's instructions, unchanged, as the caller's catalog received them, up to
-max-instructions characters (10,000 by default; longer ones are cut, with a note saying so). Clients cut it again,
much sooner: Claude Code keeps about 4,000 characters of a server's instructions, so only the start of a long upstream
text reaches the model (see docs/clients.md). And search_tools
returns the input schemas of its best few matches (-search-schemas, 3 by default), so a call usually follows a
search directly.
Logs and metrics record tool names, outcomes and timings. Queries, arguments, results and tokens never appear in them; docs/privacy.md has the details. The transport is streamable HTTP without sessions, for MCP 2026-07-28 clients and older ones, so a restart or a load balancer doesn't break a client's connection.
It works with any upstream that speaks streamable HTTP MCP and authorizes by bearer token. docs/agentgateway.md shows a complete agentgateway setup, which the end-to-end tests run.
Related MCP server: MCPJungle mcp gateway
Early development. The tools, their arguments and the settings may still change before 1.0.
Homebrew, on macOS or Linux:
brew install --cask datolabs-io/tap/mcp-toolsearch-proxyPackages (.deb, .rpm), archives and a container image are attached to each
release. See docs/deploy.md.
mcp-toolsearch-proxy fetch-model -model-dir ./model # once: ~530 MB, checked against pinned digests
mcp-toolsearch-proxy -upstream https://gateway.example.com/mcp/all -model-dir ./model-embedder none skips the model and searches lexically only. docs/configuration.md lists
every setting, as mcp-toolsearch-proxy -h does; each has an environment variable too. Then connect a client:
docs/clients.md.
Clients that already defer MCP tools and search them on demand, as Claude Code does, gain less from the proxy; see when you don't need this.
The repository holds an evaluation set of made-up tools, described in English, and questions people ask about them in English and Lithuanian. Recall at 5 today:
Search | English | Lithuanian |
lexical only ( | 52% | 0% |
hybrid with the built-in model | 81% | 79% |
Words alone can't connect a Lithuanian question to an English description. The model can. Tests hold changes to ranking to these numbers.
On a made-up catalog of 500 tools, a model given 30 questions reaches the right tool nearly as often through the proxy (90%) as with every tool loaded (95%), at about half the cost per task, and more often than with Anthropic's tool search (87%). docs/benchmarks.md has the numbers, what a client loads in each mode at up to 1,490 tools, and how to run the benchmarks.
mise install # the pinned toolchain and the git hooks
mise run ci # lint, scan and unit tests, as CI runs them
mise run test:model # the built-in model against its reference implementation and the evaluation set
mise run e2e:up # agentgateway, the proxy and fixture MCP servers, with Docker Compose
mise run test:e2e # the end-to-end tests, against that stack or any at E2E_SEARCH_URL and E2E_ALL_URL
mise run docs:config # regenerate docs/configuration.md after changing a flagSee CONTRIBUTING.md and ARCHITECTURE.md.
MIT. The built-in model is published by Minish under the MIT licence and is downloaded, not distributed, by this project.
Call a tool that only reads (readOnly in search_tools results), with arguments matching the input schema from search_tools or describe_tool. Returns the tool's own result, or, when the arguments do not fit, what is wrong and the schema. Tools that may change anything are refused: call those with call_write_tool.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The tool's name, as search_tools gave it. | |
| arguments | No | The tool's arguments, as its input schema describes them. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description is consistent while adding real value: it discloses the success return ("the tool's own result") and the failure mode ("what is wrong and the schema") when arguments do not fit. It does not address openWorldHint=true or idempotentHint=false, so the agent gets no warning that repeated reads may yield different results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly packed sentences with no filler: the scope and eligibility rule come first, then return/error behavior, then the refusal rule. Every clause carries actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter dispatch tool with no output schema, it covers eligibility, argument source, return shape, and refusal behavior. Minor omissions remain: how to obtain the schema (search_tools vs describe_tool ordering) and the distinction from the sibling call_read_tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents name and arguments, and the description largely restates them. It adds marginal provenance value by tying name to search_tools and arguments to the tool's own input schema, but no guidance on the nested arguments object beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ("call a tool that only reads") plus the exact selection criterion (readOnly in search_tools results), and names the write-tool counterpart. An agent can tell it apart from call_write_tool without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear when-to-use rule keyed to the readOnly flag and an explicit alternative ("call those with call_write_tool"), which is strong guidance. The gap is that the sibling call_read_tools (plural, batch variant) is never mentioned, leaving the agent to guess which of the two read paths to pick.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call up to 10 tools that only read (readOnly in search_tools results) at once, in parallel: each entry of calls is a name and arguments, as call_read_tool takes them. Returns every call's result in order, each labelled with its number, its tool and whether it failed; one that fails does not stop the others. Tools that may change anything are refused.
| Name | Required | Description | Default |
|---|---|---|---|
| calls | Yes | The calls, 1 to 10, each a tool's name and its arguments. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, and the description goes well beyond them: parallel execution, order-preserving results, per-call labelling with index/tool/failure status, and failure isolation ('one that fails does not stop the others'). That is exactly the behavioral context an agent needs to decide whether batching is safe and how to read partial failures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the verb, the limit, and the parallelism, then the return contract and the write-refusal guard. It is dense and slightly run-on but every clause carries information; nothing is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Though there is no output schema, the description fully spells out the return shape (ordered results, numbered, tool-labelled, failure-flagged) and the partial-failure semantics. Combined with complete parameter documentation and a declared safety profile, an agent has everything needed to invoke and interpret this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the nested items already document name and arguments, so the baseline applies. The description adds only the cross-reference that each entry has the same shape call_read_tool takes, which is a minor clarification rather than new meaning about the single `calls` parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and scope (call up to 10 read-only tools at once, in parallel) plus a hard constraint that write-capable tools are refused, which separates it cleanly from call_write_tool and the single-call call_read_tool without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context for use (batch multiple read-only calls in parallel) and an explicit exclusion (tools that may change anything are refused), plus the 10-call ceiling. It never explicitly says 'for a single call use call_read_tool', so the routing decision for the trivial case is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call a tool that may create, change or delete something (not readOnly in search_tools results), with arguments matching the input schema from search_tools or describe_tool. Returns the tool's own result, or, when the arguments do not fit, what is wrong and the schema. Prefer call_read_tool for tools that only read.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The tool's name, as search_tools gave it. | |
| arguments | No | The tool's arguments, as its input schema describes them. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the description does not need to repeat the risk profile. It does add useful behavior beyond the annotations, though: it explains that the call returns the wrapped tool's own result, and that when the arguments do not fit, it returns the problem plus the schema, which is a concrete retry signal. It stops short of saying anything about confirmation, side-effect scope, or partial failure, so it is strong but not complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, with the highest-value routing rule front-loaded in the first clause. Every sentence carries distinct information: what qualifies, where the arguments come from, what comes back, and which alternative to prefer.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a generic dispatcher with a free-form nested `arguments` object and no output schema, so its description has to carry a lot of meaning; it covers the invocation contract, the source of the argument schema, and the error shape. The only real gap is behavioral detail on destructive side effects and confirmation, which the annotations only partly fill in.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already gives 100% parameter coverage, and the description still adds meaning by saying the arguments object has no fixed shape: it is whatever the discovered tool's schema says, where that schema came from search_tools or describe_tool. It also pins down the `name` semantics as "as search_tools gave it." This adds modest workflow context, but it does not explain what happens with missing or extra arguments beyond an error return.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific operation with a clear verb and resource: "Call a tool that may create, change or delete something", and it qualifies the scope using a concrete signal ("not readOnly in search_tools results"). It also names the sibling it is not intended for ("Prefer call_read_tool"), so an agent can choose between them without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly routes between alternatives: use this for non-readOnly tools, and "Prefer call_read_tool for tools that only read." It also states a prerequisite workflow: arguments must come from the input schema reported by search_tools or describe_tool, which tells the agent what to do before invoking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the full description and input schema of tools found with search_tools.
| Name | Required | Description | Default |
|---|---|---|---|
| names | Yes | Names of tools, as search_tools gave them; at most 10. |
| Name | Required | Description |
|---|---|---|
| tools | Yes | |
| similar | No | For each unknown name, the tools closest to it. |
| unknown | No | Names no tool of the catalog has. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds that both description and input schema are returned, which is somewhat redundant with the existing output schema. There is no note on behavior for unknown or invalid names, or on the 10-name cap (that lives only in the schema), so this is a baseline 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the verb and the payload, zero filler. Every word carries information and nothing is buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no explanation, and the tool is low-complexity with one well-documented parameter. The only omission is edge-case behavior (what happens when a name is not found), which keeps it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter is documented with both provenance ('as search_tools gave them') and a limit ('at most 10'). The description echoes the provenance but adds no syntax or format detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description has a specific verb ('Return') and a specific resource ('the full description and input schema of tools'), and it ties itself to the sibling search_tools as the producer of the names. An agent can tell it apart from search_tools (discovery) and call_read_tool/call_write_tool (invocation). It stops just short of 5 because it does not explicitly say what it is *not* for relative to those call tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'tools found with search_tools' establishes the workflow: search first, then describe before invoking. That is clear contextual guidance, but there are no explicit exclusions (e.g., 'do not use this to execute a tool' or 'use call_read_tool to actually run it'), so it stays below the 5 bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the tools that can do what you describe, among all the tools you may use. Returns names and short descriptions, best match first, with the input schemas of the best few; read the input of any other with describe_tool. Give queries instead of query to find several things at once, such as a tool for the task and one for a value the user did not give.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many tools to return for each query, 1 to 25; 8 when omitted. | |
| query | No | What you want to do, in your own words and in any language. | |
| queries | No | Instead of query, 1 to 5 things to find at once, each with results of its own. | |
| schemas | No | Include the input schemas of the best matches, so a call can follow without describe_tool; true when omitted. |
| Name | Required | Description |
|---|---|---|
| tools | No | The best matches of query, best first. |
| total | Yes | How many tools the catalog holds in all. |
| results | No | With queries, the best matches of each, in the order asked. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already cover safety (readOnlyHint, idempotentHint, openWorldHint=false), so the description's burden is lighter. It nonetheless adds real behavioral detail: results are ordered best match first, each result carries a name and short description, and input schemas are included only for the best few. Return-shape details are partly handled by the output schema, so this is not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in the first sentence and the follow-up sentences each carry a distinct instruction (ranking, schemas, describe_tool, multi-query). The final sentence is somewhat convoluted in phrasing ("one for a value the user did not give") but its content earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description need not enumerate return values, and it correctly refrains while still noting ranking order and partial schema inclusion. Annotations cover the safety profile and the schema covers all four parameters, so an agent has what it needs. The multi-query behavior could be slightly clearer about how results are grouped per query, which keeps this from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents limit, query, queries, and schemas including their defaults, so the baseline is satisfied by the schema. The description adds the useful nuance that queries exists to answer several needs simultaneously (with an example) rather than merely being an array form of query. That is incremental value but not enough to exceed the schema-driven baseline by much.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ("Find the tools that can do what you describe") and scopes it to "all the tools you may use." It distinguishes itself from the sibling describe_tool by stating that schemas are returned only for the best few and that others require describe_tool, so an agent can separate this discovery tool from the invocation tools without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear conditional: use queries instead of query when several things must be found at once, with a concrete example (a tool for the task plus one for a missing value). It also routes the agent onward to describe_tool for tools outside the returned best few. There is no explicit statement of when not to use this tool, so it falls short of the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.9.0call_read_toolcall_read_toolscall_write_tooldescribe_toolsearch_toolsScored across 5 tools
Each tool has a clearly distinct role in the proxy workflow: search_tools discovers tools, describe_tool returns schemas, call_read_tool and call_read_tools execute single vs batch read-only calls, and call_write_tool executes mutating calls. The singular/plural read pair is the only close pair, but their batch-vs-single distinction is explicit in the descriptions.
All names follow a consistent snake_case verb_noun pattern: search_tools, describe_tool, call_read_tool, call_read_tools, call_write_tool. The plural suffix on call_read_tools is a readable and intentional variation for batching.
Five tools is well-scoped for a proxy server whose job is to discover, inspect, and invoke other tools. Each tool earns its place, with no redundant surface area.
The surface covers discovery, schema inspection, single and batch read execution, and write execution, which are the core operations for this proxy domain. Minor gaps include no batch write operation and no explicit enumerate-all-tools call, though search_tools can approximate discovery.
Search, vet & assemble MCP servers from your agent: verified tools, risk labels, and trust scores.
The OpenRouter for tools. One MCP connection gives any AI agent 254 hosted tools, pay per call.
Free search over ~50k agent tools: paid x402 APIs and MCP servers. Price, networks, how to call.
