Tool Guardian

Tool Guardian

Status: active development -- changelog

mcp-name: io.github.LuminariSoftwares/tool-guardian

Seven MCP servers for 1,084 tokens instead of 20,005.

One MCP server in front of all your others, so the model fetches a tool schema only when it needs one.

Quick start (60 seconds)

Nothing to install: uvx runs it from PyPI. The example server below is the MCP filesystem server, which runs with npx, so that one line needs Node.js — the router itself is Python 3.9+ and standard library only.

uvx tool-guardian --version

uvx --from tool-guardian tool-guardian-setup add files -- npx -y @modelcontextprotocol/server-filesystem "$HOME" uvx tool-guardian --selftest claude mcp add --scope user tool-guardian -- uvx tool-guardian # or any client: see "Run" below

Or tell your coding agent: Install tool-guardian (docs: https://raw.githubusercontent.com/LuminariSoftwares/tool-guardian/main/llms.txt) and route my MCP servers through it.

Prefer it installed? pip install tool-guardian, then drop the uvx prefixes (tool-guardian-setup add ..., tool-guardian --selftest).

Success looks like added 'files' to ~/.tool-guardian/mcp.json, then from --selftest 1 backend(s) up, 14 tools reachable. and a router tools cost ~N tokens vs ~M line. Already have servers in Claude Desktop, Cursor or Windsurf? tool-guardian-setup import copies them instead of add. In the client, ask for something one of your servers does; the model should call list_capabilities (or search_capabilities) and then call_tool.

What it looks like in practice

A real session against two servers (files and git), abridged only where marked. The model asks for the catalogue, narrows to one server, checks one tool's arguments, then calls it:

> list_capabilities()

[files] 14 tools: read_file, read_text_file, read_media_file, read_multiple_files, write_file, edit_file, create_directory, list_directory, list_directory_with_sizes, directory_tree, move_file, search_files, get_file_info, list_allowed_directories [git] 12 tools: git_status, git_diff_unstaged, git_diff_staged, git_diff, git_commit, git_add, git_reset, git_log, git_create_branch, git_checkout, git_show, git_branch

NEXT STEP: use search_capabilities with a keyword (or list_capabilities with one server name) to see a tool's args, then call_tool.

list_capabilities(server="files")

files.read_file: Read the complete contents of a file as text. DEPRECATED: Use read_text_file... args: path:string, ?tail:number, ?head:number files.read_text_file: Read the complete contents of a file from the file system as... args: path:string, ?tail:number, ?head:number ... 11 more tools ... files.list_allowed_directories: Returns the list of directories that this server is allowed to access.... args: (no arguments)

NEXT STEP: you have not answered the user yet. Pick the tool above that does the job and use call_tool with server files, that tool's name, and the args listed under it.

describe_tool(server="files", tool="read_text_file")

files.read_text_file: Read the complete contents of a file from the file system as... required args: path:string

NEXT STEP: use call_tool with server files, tool read_text_file, args: path:string, ?tail:number, ?head:number.

call_tool(server="files", tool="read_text_file", args={"path": "project/README.txt"})

hello from tool-guardian

NEXT STEP: answer the user from this result.

Only the router's own six tools were in the model's context the whole time; the 26 backend tools were never sent.

Proof

The result line is this repo's bench, run against the recorded tools/list answers of seven public MCP servers (no network, no model; abridged where marked):

$ python bench/bench_tokens.py

Tool-Guardian Token Benchmark

Token counting method: estimate:chars/3.5

| server | tools | tokens (full schemas) | ... | Total | 95 | 20005 |

Every request: 20005 tokens of tool schemas without tool-guardian, 1084 with it (94.6% less).

<!-- c1 --><!-- c2 -->

Run 2026-11-05 on the v0.10.0 tag. Test suite (pip install -r requirements-dev.txt && python -m pytest -q), run 2026-11-05:

428 passed, 4 skipped in 85.82s (0:01:25)

--selftest proves the *saving* and that your backends start — it does not prove your model will drive the router in your harness. See Model requirement.

One MCP server in front of all your others. Tested with Claude Code, OpenCode, Cline and Continue (one scripted-model turn per client, see Works with ); Claude Desktop, Cursor and other stdio MCP clients: expected, not yet tested.

Quick start · Works with · DeepSeek Harness · Install both · First 5 minutes · Why · Two ways to run it · Architecture · Install · Measure it · Output ladder · DSH bundle · Compatibility · Changelog

An MCP server that sits in front of your other MCP servers and exposes 6 router tools (8 with skills) instead of dozens of specific ones: four generic ones to list, search, describe and call the tools behind it, plus two for tool-group costs and archived results (see Tools) — discovering the rest on demand — so tool definitions stop eating your context window before the model reads a word.

The router never talks to the model backend, so it does not matter whether Ollama, LM Studio, vLLM or llama.cpp serves your model; what matters is that your client's model calls tools (run with Ollama; the others expected, not yet tested).

Companion to Context Guardian: Context Guardian compacts the conversation before the window fills; Tool Guardian keeps the tools from filling it in the first place. Two halves of the same problem.

When *not* to use the router

It is the wrong tool in two cases, and saying so is cheaper than finding out:

• Your client already searches tools for you. Some clients (and some model APIs) load tool definitions on demand themselves. Putting a router under that adds a hop and a second catalogue for no saving.
• You run a handful of small servers. The router's own tools cost about 1,100 tokens of tools/list; one small server behind it is close to break-even (--selftest prints the real arithmetic for *your* servers before you commit to it). The saving grows with every server added and is largest where it matters most — a 32K local model with half a dozen servers.

It also does not help if your model will not call tools reliably in the first place: see Model requirement.

Works with

pip install tool-guardian, then one entry in your client. Every example below starts the same command, tool-guardian, which reads ~/.tool-guardian/mcp.json: tool-guardian-setup import fills it from the servers you already use.

What "full turn" means. On Linux, 2026-10-10, each client got the example's tool-guardian entry unchanged (Claude Code through claude mcp add-json; OpenCode and Continue with a test model provider added beside it; Cline the file as is) and talked to a scripted model (tests/clients/mock_model.py, no real model, no API key). The client sent tool-guardian's router tools to the model. The model's list_capabilities call went through tool-guardian to a stub MCP server, and the answer came back to the model. tool-guardian's call log recorded the client by name (claude-code, opencode, @cline/core, continue-cli-client). Re-run it: pip install -e . then python tests/clients/run_clients.py. This proves the wiring, not that *your* model will use the router: see Model requirement.

The Claude Code hook in a live session. The hook command from settings.json with --mode deny added (wrapped to