
“How much space is left on the NAS?”
It is a small question. Yet an assistant connected to several Model Context Protocol (MCP) servers might receive the definitions for storage tools, Git operations, backup jobs, and everything else before it can answer. Each definition takes room: a name, a description, parameter types, perhaps several nested objects.
For a local model, that is a lot of reading before doing very little. It is the same practical concern behind my local-model audit: what matters is whether the whole system finishes useful work within the machine’s limits.
How do you keep access to all your tools without making a small model read all of them on every turn?
This guide starts with a working discovery example, then connects the pattern to existing MCP servers. The examples use FastMCP 4.1.4 and Python 3.10 or newer, with commands for Linux and macOS. The first example uses invented data and needs no model, account, API key, or NAS.
Where the extra context comes from
An MCP server publishes tools. The host is the application running the conversation, connecting to servers, and deciding what to send to the model. Ollama can serve the model, but an agent application still has to execute its requested functions and return their results. Ollama’s tool-calling documentation shows that loop.
These are separate responsibilities. Fetching a catalog with MCP’s tools/list does not require the host to put every definition into the next model request. The MCP tools specification leaves presentation to the implementation.
Consider an illustrative catalog of 30 tools averaging 300 tokens each. That is 9,000 tokens of definitions, before conversation history or results. The arithmetic is useful; the 300-token average is an assumption, not a measurement of your server.
There are three places to reduce the work:
| Approach | What changes | Who needs to support it |
|---|---|---|
| Tool discovery | The model searches for a few definitions when needed | A server or gateway can provide this |
| Host-side routing | The application selects relevant definitions before asking the model | The agent application |
| Programmatic tool calling, or Code Mode | Generated code combines calls and filters intermediate results | A host with an isolated execution environment |
The MCP project’s client best practices describe progressive discovery and programmatic calling. They solve different costs: definitions entering context, and results travelling through it.
For the first experiment, discovery is enough.
1. Create a small, isolated example
In a new directory:
mkdir lean-mcp
cd lean-mcp
python3 -m venv .venv
source .venv/bin/activate
python -m pip install "fastmcp==4.1.4"
The exact version keeps the walkthrough reproducible. When upgrading later, rerun the check below; the FastMCP installation guide also recommends pinning versions for production.
Save this as server.py:
from typing import Literal
from fastmcp import FastMCP
from fastmcp.server.transforms.search import BM25SearchTransform
mcp = FastMCP("Lean tools demo")
@mcp.tool
def get_pool_usage(name: Literal["tank"] = "tank") -> dict:
"""Get NAS storage pool capacity and free disk space."""
return {"pool": name, "total_gib": 1000, "free_gib": 240, "demo": True}
@mcp.tool
def get_service_status(name: Literal["backup", "media"]) -> dict:
"""Check whether a named application service is running."""
return {"service": name, "state": "running", "demo": True}
@mcp.tool
def list_recent_backups() -> list[dict]:
"""List recent backup jobs and their completion status."""
return [{"job": "nightly", "status": "completed", "demo": True}]
mcp.add_transform(BM25SearchTransform(max_results=3))
if __name__ == "__main__":
mcp.run()
The three functions are deliberately ordinary. They return fixed sample values, and none changes anything. Their descriptions also contain the words a person might search for, such as “NAS”, “capacity”, and “free disk space”.
The line that changes discovery is BM25SearchTransform(max_results=3). FastMCP’s search transform advertises two tools: search_tools and call_tool. Search returns matching definitions, including their input schemas; the second tool invokes a discovered operation.
BM25 ranks text matches without an embedding model. A result limit of three is a starting point, not a claim that every task needs exactly three tools.
With only three short functions, this example may add overhead. Its purpose is to make the mechanism visible before applying it to a larger catalog.
2. Check discovery before involving a model
Save the following as check.py, beside server.py:
import asyncio
import json
from pathlib import Path
from fastmcp import Client
async def main():
async with Client(Path(__file__).with_name("server.py")) as client:
visible = sorted(tool.name for tool in await client.list_tools())
print("Visible:", ", ".join(visible))
assert visible == ["call_tool", "search_tools"]
found = await client.call_tool(
"search_tools", {"query": "NAS pool free disk space"}
)
print("Discovered:", json.dumps(found.data, indent=2))
assert 1 <= len(found.data) <= 3
assert any(
tool["name"] == "get_pool_usage" and "inputSchema" in tool
for tool in found.data
)
result = await client.call_tool(
"call_tool",
{"name": "get_pool_usage", "arguments": {"name": "tank"}},
)
print("Result:", json.dumps(result.data, sort_keys=True))
assert result.data["free_gib"] == 240
assert result.data["demo"] is True
asyncio.run(main())
Run it inside the activated environment:
python check.py
The client starts the server over standard input and output, then closes it when the check finishes. There is no HTTP port to open.
Alongside FastMCP’s startup logging, look for:
Visible: call_tool, search_tools
The discovered definitions should include get_pool_usage and its inputSchema. The final line should be:
Result: {"demo": true, "free_gib": 240, "pool": "tank", "total_gib": 1000}
Those are sample values, not a reading from your storage.
This check exercises listing, search, and invocation through the generic wrapper. It also checks that search returned a schema, rather than just a promising tool name. The client reads result.data using FastMCP’s structured result interface.
There is an awkward naming detail here: client.call_tool(...) is a Python client method. The string "call_tool" inside it is the name of the wrapper advertised by the transform. Underneath, MCP still uses its normal tools/call request.
3. Connect your agent application
For a host that accepts the common mcpServers configuration, add an entry like this:
{
"mcpServers": {
"lean-demo": {
"command": "/absolute/path/lean-mcp/.venv/bin/python",
"args": ["/absolute/path/lean-mcp/server.py"]
}
}
}
Replace both paths. From the example directory, this prints the values to use:
python -c 'from pathlib import Path; print(Path(".venv/bin/python").absolute()); print(Path("server.py").absolute())'
Merge the entry into your existing configuration rather than replacing the whole file. Hosts differ in where they store it and which format they accept; FastMCP documents the common JSON configuration pattern.
Restart or reconnect the MCP integration, then start a fresh conversation. Select a model that supports tool calling and ask:
Use the demo tools to tell me how much free space the tank pool has.
Inspect the tool trace. A successful path searches for the storage operation, receives its definition, invokes it through call_tool, and answers that the demo reports 240 GiB free. An answer containing that number without a corresponding tool result is not a successful test.
If your model stalls at discovery, that is useful evidence. A smaller menu does not automatically make the model better at following a multi-step procedure.
4. Wrap existing MCP servers
Once the demo works, the same transform can sit in front of servers you already run. Create a separate gateway.py:
from fastmcp.server import create_proxy
from fastmcp.server.transforms.search import BM25SearchTransform
config = {
"mcpServers": {
"nas": {
"url": "http://127.0.0.1:9000/mcp",
"transport": "http",
},
"git": {
"url": "http://127.0.0.1:9001/mcp",
"transport": "http",
},
}
}
gateway = create_proxy(config, name="LeanGateway")
gateway.add_transform(BM25SearchTransform(max_results=3))
if __name__ == "__main__":
gateway.run()
The loopback URLs are placeholders for existing MCP HTTP endpoints. This code does not start them. A NAS web interface or a Git service’s ordinary REST API is not an MCP endpoint.
Begin with test servers or credentials restricted to reading. Configure authentication using each upstream server’s supported method, keeping secrets outside the article and committed files.
The FastMCP proxy provider combines the servers and prefixes tool names. An upstream get_pool_usage on the nas server becomes nas_get_pool_usage. Use the exact name returned by search, since real servers will have different tools and arguments.
Point your host entry at gateway.py. For the comparison, disable its direct connections to the same upstream servers; otherwise their full catalogs may still be entering the prompt alongside the gateway. Reconnect and use a fresh conversation again.
Keep the distinction between discovery and permission clear. Hiding a tool from a catalog does not revoke permission to call it. The search transform itself is not an authorization boundary. Enforce permissions when executing the underlying operation, including calls made through the wrapper.
The local demo and the two-server proxy pattern were checked with test fixtures for this guide. No live NAS or Git service was queried, and these checks do not establish how reliably a particular LLM will use the tools.
When the extra search becomes the problem
The gateway makes the catalog smaller, but asks the model to do more steps:
Question → search_tools → read schema → call_tool → answer
Also, a schema returned as tool output does not automatically become a native function in the model’s next request. The generic wrapper is what makes the example usable without that host feature.
If you control the agent application, try selecting a small set of tools before the model runs:
Question → host retrieves relevant schemas → model calls a typed tool → answer
For a storage question, the application might supply only get_pool_usage and get_pool_health, with their real parameter schemas. Keep a search fallback for requests the first selection misses.
I would start with names, useful descriptions, and a few aliases. “NAS capacity” and “free disk space” should lead to the same capability. BM25 is lexical search: it does not acquire an understanding of synonyms merely because the query is a sentence. Add embeddings only if real queries reveal a vocabulary problem that simpler descriptions cannot fix.
Retrieval must also consider conversation context. “What about the other pool?” cannot be routed well from that sentence alone. Refresh the catalog when tools change, and allow no match rather than forcing an unrelated operation.
This is an architecture to evaluate, not a measured rule about model size. Parameter count alone does not tell you whether discovery, routing, or code execution will work best.
Keep the results small too
After trimming definitions, look at what your tools return. A short question can still produce thousands of log lines.
For a recurring task, a server-defined operation such as get_storage_health(pool) could fetch capacity, alerts, and scrub status, then return the relevant fields together. Include the observation time, any failed checks, and whether data was truncated. “No alerts” and “the alerts request failed” must remain different outcomes.
Code Mode lets the model write a program that performs this orchestration. Cloudflare’s implementation provides an execution environment and tool-dispatch interfaces for that approach.
It is worth exploring when intermediate data dominates the workload and the model can write dependable code. For a small model doing the same storage check repeatedly, a fixed workflow may be easier to verify. Generated code adds another thing that can fail.
If you introduce code execution, isolate it and enforce access at each underlying call. Approval for a script must not silently grant permission for every deletion, write, or external transfer it attempts.
Measure the whole task
Use the same requests, model, context setting, and generation settings for each configuration. Start with the current full catalog, then try the search gateway. Compare host-side routing only if your application supports it.
Include ordinary requests, ambiguous follow-ups, tasks needing multiple tools, and questions that should use no tools at all.
| Record | What it tells you |
|---|---|
| Correct task completion | Whether the answer came from the right operation and data |
| Tool and argument errors | Whether the model selected and invoked the operation correctly |
| Retrieval recall at three | Whether the required tool appeared among the first three candidates |
| Total input and output tokens | Whether discovery and retries erased the initial saving |
| Model rounds and elapsed time | What the user actually waits for |
| Unexpected actions | Whether a smaller prompt hid a more serious regression |
Use the runtime’s token accounting for every model round, not just the initial request. Keep warm-cache and cold-cache comparisons separate. A stable prompt can benefit from caching, so changing the tool list may save context while losing some cache reuse.
If the gateway makes a small catalog slower, keep direct tools. If search repeatedly misses the needed operation, fix retrieval before blaming the model. If discovery works but generic arguments keep failing, try host-selected typed tools.
So how do you keep access to all your tools without making a small model read them all on every turn? Keep the catalog in the application or gateway, retrieve the definitions needed for the task, and pass back results the model can actually use.
The NAS question should finish with a storage reading. The measure of success is getting there reliably, with less work along the way.
Buy Me a Coffee