# McpGuard: a rule-based security proxy for MCP traffic

> A proxy between an agent and its MCP servers: scans results for injection, masks PII, enforces access and logs decisions to a hash-chained audit log.

- What it does today: Sits between an agent and its MCP servers over stdio (`wrap`) or HTTP (`serve`), scans tool results and resource contents for prompt injection, masks personal data, enforces access by tool, role and dangerous capability combination, pins a server's tool definitions and writes every decision to a hash-chained audit log. Anyone wiring MCP servers into agents can try it by cloning and building the repository; it is not published on npm.
- Form: Open-Source
- Maturity: Alpha
- State: In development
- Focus: AI and AI-assisted development
- Started: 2026-09-16
- Technologies: TypeScript, Node.js, MCP, YAML, OTLP
- Tags: #ai, #mcp, #security, #prompt-injection, #pii
- Source code: https://github.com/Tunedness/McpGuard
- Source: https://muhammetsafak.com/labs/mcpguard-lab/
- Language: en-US
- Author: Muhammet Şafak

---
McpGuard's injection scan catches 100% of my 700-item corpus with 0.0% false positives. I read that number as a ceiling: the corpus and the ruleset came from the same hands. What it says and what it does not say is the subject of this entry.

## A checkpoint between the agent and the MCP server

McpGuard is a security proxy between an MCP client and its servers. Nothing changes in the client or the server; you put `wrap` (stdio) or `serve` (HTTP) where the server's own command was. It scans tool results and resource contents, masks personal data and applies per-tool `allow` / `deny` rules. Roles are mapped from the caller's identity, `servers.<name>.roles` decides who may reach a server, and dangerous combinations such as "read a file" plus "reach the network" are enforced on every call. Tool definitions are hashed into `guardlock.json` on first contact; if the list differs later, `tools/list` and `tools/call` are refused until `lock --accept` or a restart. Every decision goes to a hash-chained JSONL audit log holding masked content and a keyed fingerprint of the raw content, never the raw content. `serve` exposes each server under `/mcp/<name>` with its own rules, lock entry and connection pool; it defaults to loopback, refuses other addresses without `auth.tokens` and `http.allowed_hosts`, and has no TLS.

The starter policy observes (`mode: flag`): decisions are recorded, nothing is blocked; you measure first, then move to `enforce`.

## The scan is deterministic and limited to a closed list

The first tier uses no model: signature rules, imperative mood, hidden Unicode, decoded payloads, egress beacons and chat-frame injection, in Turkish and English. The score is computed in integers, so the verdict is byte-identical on every platform. Turkish national id, tax number, IBAN, card (checksum-gated), phone and e-mail are masked; `pii.profile: health` optionally adds institution reference numbers, clinical dates, medicine-pack serials and US SSN/Medicare ids. Names and addresses are not recognised.

Three gates are scanned: `tools/call`, `resources/read` and `tools/list`. `prompts/get`, `sampling/createMessage` and elicitation are deliberately not.

## What the 100% says

The corpus is 700 labelled items: 300 positives across 12 attack families, 400 negatives. The holdout split separates the operating point, not the rules, so 100% means "every attack family the corpus contains, at ruleset 0.1.0"; I do not know what happens against a phrasing nobody wrote a rule for. A rule engine cannot close the paraphrase gap; my answer is an off-by-default second tier, a local model you run yourself that can only raise a decision. On my machine, `gemma4:12b` through Ollama called 61 of 64 paraphrased injections an injection and 0 of 60 benign items; that is one model on a small set, not a rate. The default band also sends none of those 64 paraphrases to it: all of them score below `flag_at` in the rule engine, and 57 score exactly 0. Sending everything is the opt-in `band_from: 0`.

On latency, the corpus median is 188 bytes and at 1 KB p95 is 0.23 to 0.27 ms. Up to 32 KB p95 stayed under 20 ms in every run; above that it depends on the machine, and at 128 KB it ranged from 32.5 to 202 ms over three runs.

## On `main` today: v0.2.0 is being put together

Alpha. All of this is on `main` on GitHub; nothing is published on npm, so you clone, run `npm install && npm run build` and use `node packages/cli/dist/main.js`. I am assembling v0.2.0: the documentation is in review, the end-to-end acceptance scenario and the plan-end security review are next.

McpGuard chains with [AgentFuse](https://muhammetsafak.com/labs/agentfuse-lab/): McpGuard sits outermost and injects the session identity, AgentFuse adopts it.
