mcp-guarded-tools

An MCP server that treats a large tool surface as a governance problem: 43 domain tools sit behind 4 always-on meta-tools, and every call passes a composable chain of guardrails — scope, budgets, rate limits, schema validation, human-in-the-loop confirmation for writes, PII redaction, and an append-only audit log.

Most public MCP servers are thin API wrappers: they register every tool up front and execute whatever the model asks. That works at 5 tools. At 40+, two problems appear that this repo is built to explore:

1. Context cost — every tool schema is paid for on every request, whether used or not.
2. Blast radius — an agent loop 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.

---

Quickstart (60 seconds, zero credentials)

npm install
npm run demo

No API keys, no network calls, no database. The demo spawns the real server as a child process, drives it over the real stdio MCP transport, and prints the transcript below.

npm run build   # tsc, strict mode
npm test        # vitest — 62 tests, all offline
npm run lint    # eslint + prettier
npm run tokens  # the context-cost measurement

Requires Node 20+.

---

What the model actually sees

Tools exposed over MCP: 4
  - search_tools     find tools by keyword
  - describe_tool    get one tool's full JSON Schema
  - confirm_action   mint a single-use token for a mutating tool
  - invoke_tool      run a tool by name

Domain tools hidden behind them: 43

The model discovers tools by searching, not by receiving 43 schemas up front.

---

Measured context cost

Both surfaces expose the same 43 tools. The difference is what lands in the context window before the conversation starts.

Surface	Tokens
A. All 43 schemas dumped (conventional tools/list)	2,913
B. Tool-search facade (4 meta-tools)	486
Difference	2,427 fewer tokens (83.3% smaller)

How this was counted. Each tool is serialised into the exact MCP Tool shape ({name, description, inputSchema}), the array is JSON.stringify'd with no pretty-printing, and the string is tokenized with gpt-tokenizer using the o200k_base encoding. Surface B is measured from the live tools/list response of the running server in that same run, not from a hand-written copy. Counts cover the tool-definition payload only — protocol envelope and system prompt are identical for both and excluded.

Reproduce:

npm run demo    # prints surface B measured live  -> 486
npm run tokens  # standalone; uses static schema copies -> 477

The two commands differ by 9 tokens (486 vs 477) because npm run tokens measures a static copy of the meta-tool definitions while npm run demo measures what the server actually emitted. 486 is the honest number — it is what a client really receives. The gap is left visible rather than reconciled away.

This is not a free win, and the break-even is measured too. Surface B moves cost from startup to run time: discovering a tool costs a search_tools reply (178 tokens for a 5-result response) and, when the schema is needed, a describe_tool reply (88 tokens for orders.refund_order). At ~266 tokens per discovery cycle, the 2,427-token saving is repaid after roughly 10 search+describe cycles in a single session. Below that, the facade wins; above it, dumping every schema would have been cheaper. Sessions that touch a handful of tools out of a large catalogue are the case this design targets — a session that methodically uses most of the catalogue is not.

Scaling note: surface B is fixed at 4 schemas regardless of catalogue size, so the gap widens as tools are added. It also narrows to nothing if the catalogue is small — at ~10 tools this indirection is not worth it.

---

Architecture

flowchart TD
    C[MCP client] -->|stdio JSON-RPC| M{{4 meta-tools}}
    M --> S[search_tools]
    M --> D[describe_tool]
    M --> K[confirm_action]
    M --> I[invoke_tool]

    S -.-> R[(Tool registry<br/>43 tools)]
    D -.-> R
    K -->|mints single-use<br/>args-bound token| T[(Session state)]

    I --> G1
    subgraph GC [Guardrail chain — first denial short-circuits]
        direction TB
        G1[1 · scope<br/>allow-list, default-deny] --> G2[2 · budget<br/>requests + tokens]
        G2 --> G3[3 · rate limit<br/>sliding window per tool]
        G3 --> G4[4 · validation<br/>Zod parse + coerce]
        G4 --> G5[5 · confirmation<br/>required for mutating]
    end

    G5 -->|allowed| H[Tool handler<br/>tenant-filtered data]
    H --> RD[PII redaction<br/>in + out]
    RD --> C

    G1 & G2 & G3 & G4 & G5 -.->|denied| A
    RD -.-> A[(Audit log<br/>append-only JSONL)]
    T -.-> G5

Chain order is cheap-before-expensive, and confirmation is deliberately last so it binds to validated arguments — otherwise {"qty": "5"} and {"qty": 5} would hash differently and describe the same call.

Every outcome, allowed or denied, is written to the audit log with arguments redacted.

---

Demo transcript

Produced by npm run demo on Node 24.18.0. Reproduced verbatim; only long JSON bodies are elided where the demo itself truncates them.

--- 1. What the model actually sees: tools/list ---
Tools exposed over MCP: 4
  - search_tools: Find domain tools by keyword. Returns name, domain, one-line s...
  - describe_tool: Return the full description and JSON Schema for one tool disco...
  - confirm_action: Issue a single-use, time-limited confirmation token for a muta...
  - invoke_tool: Run a domain tool by name. Arguments are validated against the...

Domain tools hidden behind them: 43. The model never receives these 43 schemas up front.

--- 2. Tool-search discovery (instead of prompt-dumping) ---
OK      search_tools({query:"money back to a buyer"})
        {
          "query": "money back to a buyer",
          "total_registered": 43,
          "returned": 1,
          "results": [
            {
              "name": "orders.refund_order",
              "domain": "orders",
              "summary": "Refund an order. Mutating; requires confirmation.",
              "mutating": true,
              "score": 2.5
            }
          ]
        }

--- 3. A normal read call (allowed) ---
OK      invoke_tool(invoices.total_outstanding)
        {
          "tool": "invoices.total_outstanding",
          "result": { "outstanding": 1500750 },
          "usage": { "requests": 1, "tokens": 9, "maxRequests": 30, "maxTokens": 20000 }
        }

--- 4. Argument validation rejects a malformed call ---
DENIED  invoke_tool(orders.search_by_status, status:"exploded")
        {
          "error": "INVALID_ARGUMENTS",
          "message": "status: Invalid enum value. Expected 'pending' | 'paid' | 'shipped' | 'cancelled' | 'refunded', received 'exploded'; limit: Number must be less than or equal to 100",
          ...
        }

--- 5. Out-of-scope tool is denied (tenant-style isolation) ---
DENIED  invoke_tool(admin.purge_tenant_data)
        {
          "error": "OUT_OF_SCOPE",
          "message": "Tool 'admin.purge_tenant_data' is not in this session's allow-list.",
          "details": { "tool": "admin.purge_tenant_data", "tenantId": "acme" }
        }

--- 6. Write blocked pending confirmation, then allowed after confirm ---
DENIED  invoke_tool(orders.refund_order) — no token
        {
          "error": "CONFIRMATION_REQUIRED",
          "message": "Tool 'orders.refund_order' is mutating and requires confirmation. Call 'confirm_action' with the same tool and arguments to obtain a confirmation_token, then retry.",
          "details": { "tool": "orders.refund_order", "mutating": true }
        }
OK      confirm_action(orders.refund_order)
        {
          "confirmation_token": "14060221-8c4e-4e1d-a784-b068c624c5a7",
          "expires_at": "2026-08-16T06:29:07.880Z",
          "single_use": true,
          "preview": "orders.refund_order({\"orderId\":\"ORD-1002\",\"amount\":25000}) — mutating action, expires in 120s, single use."
        }
OK      invoke_tool(orders.refund_order) — with token
        {
          "tool": "orders.refund_order",
          "result": { "orderId": "ORD-1002", "status": "refunded", "refunded": 25000 },
          "usage": { "requests": 4, "tokens": 43, "maxRequests": 30, "maxTokens": 20000 }
        }

--- 7. Replaying the same confirmation token is rejected (single-use) ---
DENIED  invoke_tool(orders.refund_order) — token replayed
        {
          "error": "CONFIRMATION_REPLAYED",
          "message": "Confirmation token has already been used. Tokens are single-use.",
          "details": { "tool": "orders.refund_order", "rejection": "replayed" }
        }

--- 8. PII redaction on tool output ---
OK      invoke_tool(customers.get_by_id)
        {
          "tool": "customers.get_by_id",
          "result": {
            "id": "CUST-0002",
            "tenantId": "acme",
            "name": "Eli Santoso",
            "email": "[REDACTED:EMAIL]",
            "phone": "[REDACTED:PHONE]",
            "tier": "free",
            "country": "MY",
            "createdAt": "2025-09-18"
          },
          ...
        }

--- 9. Rate limit fires on a burst against one tool ---
Rate limit triggered on call #6: {"error":"RATE_LIMITED","message":"Rate limit hit for 'orders.count_by_status'. Retry in 9995ms.","details":{"tool":"orders.count_by_status","retryAfterMs":9995}}

--- 10. Request budget hard cut-off ---
Budget cut-off after 19 further calls -> {"error":"BUDGET_EXCEEDED","message":"Session request budget exhausted (30/30 requests used).","details":{"requestsUsed":30,"maxRequests":30}}

--- 11. Audit log (append-only JSONL) ---
32 entries written to audit/demo-audit.jsonl. First 6:

  allowed invoices.total_outstanding   ok
  denied  orders.search_by_status      INVALID_ARGUMENTS
  denied  admin.purge_tenant_data      OUT_OF_SCOPE
  denied  orders.refund_order          CONFIRMATION_REQUIRED
  allowed orders.refund_order          ok
  denied  orders.refund_order          CONFIRMATION_REPLAYED

  allowed: 13   denied: 19

An audit line in full:

{
  "ts": "2026-08-16T06:27:07.874Z",
  "sessionId": "635792ad-a119-4067-8dfb-100787b390c8",
  "tenantId": "acme",
  "tool": "orders.search_by_status",
  "args": { "status": "exploded", "limit": 999 },
  "decision": "denied",
  "durationMs": 1,
  "guard": "validation",
  "code": "INVALID_ARGUMENTS",
  "reason": "status: Invalid enum value. Expected 'pending' | 'paid' | 'shipped' | 'cancelled' | 'refunded', received 'exploded'; limit: Number must be less than or equal to 100"
}

---

Register with Claude Desktop / Claude Code

After npm run build, add to your MCP client config (claude_desktop_config.json, or .mcp.json for Claude Code):

{
  "mcpServers": {
    "guarded-tools": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-guarded-tools/dist/server/stdio.js"],
      "env": {
        "MCP_TENANT_ID": "acme",
        "MCP_AUDIT_LOG": "/absolute/path/to/audit/session.jsonl",
        "MCP_MAX_REQUESTS": "50",
        "MCP_RATE_MAX": "5"
      }
    }
  }
}

All env keys are optional. Defaults: tenant acme, 50 requests, 20,000 tokens, 5 calls per 10s window, in-memory audit log.

---

Design decisions

Why tool-search instead of dumping every schema

Registering 43 tools means every request carries 43 schemas. The measurement above puts that at 2,913 tokens versus 486 — but the stronger argument is selection quality: a model choosing among 4 well-described meta-tools makes a different kind of mistake than one choosing among 43 similarly-named ones. search_tools also gives a natural place to filter by scope, so a session never sees tools it could not call anyway.

The trade-off is latency and the run-time token cost quantified above: two extra round trips before the first real call. The break-even (~10 discovery cycles) is stated rather than hidden.

Search here is BM25-flavoured lexical scoring, not embeddings — deliberately, so the demo runs offline with no model, no index build, and deterministic ranking that tests can assert on. Query-side stopwords are dropped; without that, "money back to a buyer" ranked an unrelated tool first because a and to matched its prose. A production deployment would swap the scorer for a vector or hybrid index behind the same interface; the meta-tool surface would not change.

Why confirmation tokens are single-use, expiring, and argument-bound

A mutating tool call is denied unless it carries a token from confirm_action. That token is:

• Single-use — consumed on first successful check. An agent stuck in a retry loop cannot turn one human approval into N writes. The demo shows the replay rejected with CONFIRMATION_REPLAYED.
• Time-limited (default 120s) — an approval granted in a different context an hour ago should not authorise a write now.
• Bound to a SHA-256 hash of the validated arguments — so approval of "refund 25,000" cannot be redirected to "refund 25,000,000". Argument keys are sorted before hashing, so key order does not matter.

What this does not give you: it is an interlock, not an authorisation system. It assumes the confirming caller is the human (or a trusted supervisor). If the same agent both requests and confirms with no human in the loop, this reduces to a two-step ritual and buys you a preview line in the audit log, nothing more. There is no identity, signature, or approver record on the token.

Why the audit log is append-only JSONL

AuditLog exposes append, all, and bySession — there is no update, delete, or clear method, so no later code path can rewrite history (a test asserts this). Records are one JSON object per line so the file stays greppable, streamable, and survives a partial write: a corrupted tail loses the final record rather than invalidating the whole document the way a truncated JSON array would. Writes are synchronous — an audit record lost on crash is worse than a few microseconds of latency.

This is tamper-evident only in the weak sense that the process never rewrites lines itself. It is not tamper-proof: anyone with write access to the file can edit it. Real immutability needs append-only media (WORM storage, an external log service, or hash-chaining) — none of which is implemented here.

What regex PII redaction does and does not give you

It gives you: removal of well-formed emails, international/grouped phone numbers, 4-group card-shaped numbers, and 16-digit national-ID-shaped numbers, on both inputs and outputs, before values reach the handler, the client, or the audit log. Patterns are configurable and applied narrowest-first (card before phone) because ordering changes the labels.

It does not give you a compliance control. Verified gaps, each reproducible against the shipped patterns:

Input	Result
amex 3782 822463 10005	not redacted — 4-6-5 grouping isn't matched
bob [at] acme [dot] io	not redacted — obfuscated form
ZW1haWxAdGVzdC5jb20=	not redacted — base64-encoded email
name: Eli Santoso, Jl. Sudirman 45 Jakarta	not redacted — names/addresses have no regex shape
card 4111111111111111	redacted, but mislabelled NATIONAL_ID (both are 16 digits — genuinely ambiguous without a Luhn check)

Regex redaction reduces casual leakage of structured identifiers. It does not detect PII described in prose, split across fields, encoded, or misspelled, and it will mislabel ambiguous digit runs. Treat it as a blast-radius reducer, not a boundary you can rely on.

What the guardrails do and do not cover

Stated precisely, because "secure" would be the wrong word for all of it:

• Scope bounds which tools a session can reach (default-deny allow-list, plus tenant filtering in the data layer as defence in depth). It does not authenticate the caller — there is no identity layer here.
• Budgets bound how much a session can consume. Denied calls are charged too, so a retry loop on bad arguments still terminates. It does not distinguish a useful call from a wasteful one.
• Rate limits bound how fast, per session and tool. A slow loop stays under them indefinitely — that is what budgets are for.
• Validation rejects malformed arguments with field-level messages. It cannot tell a well-formed malicious call from a well-formed legitimate one.
• Confirmation puts a human decision point in front of writes, with the caveats above.
• Audit makes calls reviewable after the fact. It prevents nothing on its own.

None of these stop a determined attacker who controls the client, and none address prompt injection — a model convinced to call refund_order with plausible arguments will be allowed to, once confirmed. What they do is make the damage from a confused or looping agent bounded and reviewable rather than open-ended.

---

The demo domain

A fictional multi-tenant B2B commerce back-office, generated from a fixed seed (Mulberry32 PRNG) so every run is reproducible. No external services.

Domain	Tools	Notes
orders	11	2 mutating (cancel_order, refund_order)
inventory	11	2 mutating (adjust_stock, set_price)
invoices	8	2 mutating (void_invoice, mark_paid)
customers	6	contact fields exercise PII redaction
analytics	5	read-only aggregates
admin	2	mutating; never granted to demo sessions — demonstrates scope denial
Total	43	35 read, 8 mutating

Every read tool filters by tenant in the handler as well as at the scope guard, so a scope misconfiguration still cannot return another tenant's rows.

---

Tests

62 tests, offline, no credentials:

✓ tests/redaction.test.ts  (12)  patterns, ordering, nesting, no false positives on IDs/dates/SKUs
✓ tests/registry.test.ts   (13)  registration, ranking, filters, deterministic dataset
✓ tests/guardrails.test.ts (19)  scope, budget, rate limit, validation, confirmation, handler errors
✓ tests/audit.test.ts       (7)  append-only surface, JSONL on disk, PII never logged raw
✓ tests/e2e.test.ts        (11)  real client ↔ server over stdio, spawned as a child process

The e2e suite spawns the actual built server and drives it over the real MCP stdio transport — it is not a mock. Confirmation coverage includes expiry, replay, argument-mismatch, tool-mismatch, and unknown tokens.

---

Project layout

src/
  core/       types, config (Zod), session state, budgets, tokens, audit, executor
  guardrails/ scope, budget, rate-limit, validation, confirmation, redaction
  registry/   tool registry + keyword search
  domain/     seeded dataset + 43 demo tools
  server/     McpServer wiring, stdio entrypoint
  demo/       e2e transcript, token report
tests/        vitest suites

Guardrails implement a single Guardrail interface and are composed as an ordered array in GuardedExecutor, so each is independently testable and the chain is reorderable in one place.

---

Limitations and what is not built

• stdio transport only. The SDK also ships StreamableHTTPServerTransport; it is not wired up here, and no HTTP/SSE code path is tested.
• Single session per server process. buildServer() creates one session; multi-session/multi-tenant routing over one transport is not implemented.
• In-memory state. Sessions, budgets, and confirmation tokens die with the process. The audit log is the only durable artifact.
• No authentication or identity. Scope is configuration, not authorisation.
• Search is lexical, not semantic. Stated above as a deliberate offline trade-off.
• PII redaction is regex-based, with the verified gaps tabulated above.
• The dataset is synthetic; all names, emails, and phone numbers are generated.

License

MIT © Muhammad Ridwan