MCP Guarded Tools — Large Tool Surface Governance

⚠ This is an open-source project, not client work. The numbers below were measured on a demo server running offline with no credentials — the dataset is synthetic — and the README publishes the command that reproduces each measurement, including the limits it does not cover.

The problem

Most public MCP servers are thin API wrappers: every tool is registered up front, then the server executes whatever the model asks. That works at 5 tools. At 40+, two problems appear. First, context cost: every tool schema is paid for on every request, whether used or not. Second, blast radius: an agent that can call refund_order or purge_tenant_data directly has no natural place to put a budget, an approval step, or a review trail.

What was built

43 domain tools (a fictional multi-tenant B2B back-office, generated from a fixed seed) sit behind 4 always-on meta-tools: search_tools, describe_tool, confirm_action, and invoke_tool. The model discovers tools by searching, not by receiving 43 schemas at once.

Every call passes a guardrail chain ordered cheap-before-expensive: scope (default-deny allow-list) → budget (requests + tokens) → rate limit (sliding window per tool) → argument validation (Zod) → human-in-the-loop confirmation for mutating actions. Confirmation is deliberately last so its token binds to validated arguments — the token is single-use, expires in 120 seconds, and is bound to a SHA-256 hash of the arguments, so an approval of “refund 25,000” cannot be redirected to “refund 25,000,000”. PII redaction runs on inputs and outputs, and every decision — allowed or denied — is written to an append-only JSONL audit log with the arguments redacted.

Measured, not claimed

Both surfaces expose the same 43 tools; the difference is what lands in the context window before the conversation starts. A conventional 43-schema dump measures 2,913 tokens; the 4-meta-tool facade measures 486 tokens — 83.3% smaller, counted with the o200k_base encoding from the tools/list response the running server actually emitted, not a hand-written copy.

This is not a free win, and the break-even is measured too: each discovery cycle (search + describe) costs about 266 tokens, so the 2,427-token saving is repaid after roughly 10 cycles in a single session. Below that, the facade wins; above it, dumping every schema would have been cheaper. The README states that rather than hiding it.

Stated limits

The repo refuses the word “secure” for things it does not deliver. The confirmation token is an interlock, not an authorisation system — with no human in the loop it is a two-step ritual. The regex-based PII redaction has tabulated, verified gaps (4-6-5 grouped Amex numbers, obfuscated emails, base64-encoded emails, names and addresses). The audit log is tamper-evident, not tamper-proof. And none of these guardrails stops prompt injection — what they do is make the damage from a confused or looping agent bounded and reviewable instead of open-ended.

Run it yourself

Requires Node 20+, no API keys, no network, no database:

npm install
npm run demo   # spawns the real server, driven over the real stdio MCP transport
npm test       # 62 tests, all offline

The e2e suite spawns the actually-built server and drives it over the real MCP stdio transport — it is not a mock. Public repo: github.com/ridwanspace/mcp-guarded-tools.