Reduce MCP token usage
Where the tokens go#
A normal MCP setup sends every tool's JSON schema to the model on every request. Add servers and that overhead grows with each one, even for tools the task never touches.
Lazy discovery replaces the catalog with four tools:
toolport_status— what is connected.toolport_search_tools— find the tool for the job.toolport_call_tool— run it.toolport_fetch_result— page through a large result.
The measured numbers#
From BENCHMARK.md: GPT-5.5 via the Vercel AI Gateway, three tasks (Stripe, Neon, Vercel), 5 runs each, graded for correct answers. Median totals:
| Servers | Tools | Flat tokens | Lazy tokens | Reduction | Correct (flat / lazy) |
|---|---|---|---|---|---|
| 3 | 63 | 179,181 | 47,095 | 74% | 15/15 · 15/15 |
| 6 | 183 | 471,775 | 40,354 | 91% | 15/15 · 15/15 |
Per-request tool-definition overhead went from 19,002 to 51,533 tokens in flat mode as servers doubled, while lazy stayed at 451. The benchmark is reproducible from the benchmark/ folder.
These are historical values for that tool set and harness, not a guarantee for yours. Toolport's Activity page shows your own exact catalog bytes avoided, with an estimated token equivalent (bytes divided by four).
Pick the mode per client#
| Mode | What the client sees | Use it for |
|---|---|---|
lazy (default) |
4 meta-tools | Capable models; constant context however many servers |
grouped |
4 meta-tools plus one help_<server> per server |
Weaker or local models that struggle to invent a search query |
full |
Every namespaced tool (server__tool) |
Debugging, small setups, clients with their own native tool search |
Set it globally in Settings, or per client with TOOLPORT_DISCOVERY=lazy|full|grouped. Details: Discovery modes.
Cap oversized results too#
TOOLPORT_RESULT_BUDGET=<bytes> caps oversized tool results (0 disables it); a default budget applies when it is unset.