Security Proxy

@guardbee/mcp-security-proxy

🇬🇧 English | 🇹🇷 Türkçe | 🇨🇳 中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇧🇷 Português | 🇪🇸 Español | 🇩🇪 Deutsch

A transparent security layer that sits in front of any MCP server. Blocks prompt injection attacks, masks PII in responses, and writes every request to an immutable audit log.

Telemetry is off by default. With GUARDBEE_TELEMETRY=1 it sends the server, tool, success, duration and short parameter values such as a file path; longer strings and fields like content, token or password are replaced with a placeholder. See @guardbee/mcp-telemetry.

Claude ──► MCP Security Proxy ──► Any MCP Server

│ ├─ Prompt injection detection (27 rules, EN + TR) ├─ PII + secret masking (TC, VKN, IBAN, card, phone, 22 key formats) ├─ Block or warn mode ├─ Toxic-flow (lethal trifecta) blocking └─ Hash-chained audit log

---

Features

• Prompt Injection Protection — 27 rules in English and Turkish; precise ones block, generic phrases only warn
• Tool-result injection — the same patterns applied to tool results, tagged MCP06:2025. Block mode replaces the result; warn mode prepends a warning
• Session tool pin — the first tools/list is pinned. A later description or schema change is a rug pull (MCP03:2025). Block mode keeps serving the pinned definition and refuses the drifted call
• PII Masking — TC Kimlik No, VKN, IBAN, card and phone numbers (checksum-validated), passport, SGK, MERSİS, date of birth, postal and KEP addresses, email, opt-in IP/MAC/plates, 22 provider key formats, private keys and connection strings are masked in responses
• Block / Warn Mode — each interceptor can independently run in blocking or warning mode
• Audit Log — configurable log written to console or a file
• Gateway mode — several MCP servers behind one proxy, one YAML policy (allow / deny / mask / warn)
• Toxic-flow blocking — tracks the lethal trifecta across servers and blocks the egress call that would complete it
• LLM API gateway — OpenAI- and Anthropic-compatible endpoints: gateway keys instead of provider keys, PII masking and injection checks on prompts, token and spend budgets, usage and cost in the audit log
• A2A gateway — Agent2Agent calls between agents go through the gateway: callers authenticate, injection in messages and artifacts is blocked, personal data is masked, push-notification webhooks into private networks are refused, and every call is audited
• Coding-agent hooks — guardbee-hook applies the same policy to Claude Code's and Cursor's own shell, file and web tools
• Zero Code Changes — attaches in front of any existing MCP server

---

Quick Start

npm install -g @guardbee/mcp-security-proxy

Add to claude_desktop_config.json:

{

"mcpServers": { "secure-filesystem": { "command": "npx", "args": [ "-y", "@guardbee/mcp-security-proxy", "--", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp" ] } } }

The proxy launches whatever comes after -- as the target MCP server.

---

Gateway Mode: Several Servers, One Policy

Put every MCP server behind one proxy with a guardbee-proxy.yaml. init does the move for you:

npx -y @guardbee/mcp-security-proxy@^1 init --client claude-desktop   # or cursor, claude-code, --file ./mcp.json

It moves each stdio server into ~/.guardbee/guardbee-proxy.yaml (mode 0600), backs up the client config and points it at the proxy. HTTP servers stay as they are and are reported, because they would bypass the policy. --dry-run prints both files without writing. Or by hand:

{

"mcpServers": { "guardbee": { "command": "npx", "args": ["-y", "@guardbee/mcp-security-proxy@^1", "--config", "/path/to/guardbee-proxy.yaml"] } } }

version: 1

upstreams: github: command: npx args: ["-y", "@modelcontextprotocol/server-github"] env: { GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}" } # read from the environment postgres: command: npx args: ["-y", "@guardbee/mcp-db-gateway"]

labels: # override the heuristic labels github__get_issue: [untrusted] github__create_pull_request: [egress]

tools: # what the agent sees (globs on ) hide: ["*delete_*"] descriptions: github__create_issue: "Create an issue in acme/* repositories only."

rules: # first match wins

• id: no-deletes match: { tool: "postgres__delete_*" } action: deny # allow | deny | mask | warn | approve
• match: { tool: "postgres__query", args: { table: "salaries" } } # dotted path → value, strings are globs action: mask mask: { fields: [salary, iban] } # blank these JSON keys
• match: { label: destructive } action: approve # ask the person first

taint: mode: strict # strict | approve | warn | off basis: capability # capability | data — data: block only egress calls that carry sensitive data

interceptors: anomaly: # off unless set; limits per session, sliding window enabled: true action: warn # warn | block callBurst: { count: 60, windowSeconds: 60 }

audit: sink: file filePath: ./guardbee-audit.jsonl

• Tools and prompts appear as __ .
• Toxic flow (lethal trifecta): each tool is labeled untrusted, sensitive, egress or destructive (name/description heuristics, overridable under labels). Once a session has read untrusted content (an untrusted tool or any resource) and sensitive data (a sensitive tool or any PII in a result), an egress call is blocked in strict mode and only logged in warn mode. The check spans servers: an issue read from GitHub plus a customer record from a CRM blocks a webhook on a third server.
• Rules match on tool (glob), upstream, label, session (clean | tainted) and args. mask forces PII masking for that tool even when masking is off, and mask.fields also blanks the named JSON keys in text and structuredContent. A rule's allow does not skip the toxic-flow check; relabel the tool instead.
• Topics (`topics`, `match.topic`): a rule can name a subject instead of a tool — "nothing about mergers or salaries leaves through this agent". A topic is a list of terms; text is on topic when minMatches (default 1) different terms appear. Matching folds case and Turkish letters (BİRLEŞME = birlesme), and a term may take a suffix (maaş finds maaşları, satın alma finds satın almayı); quote a term to match the whole word only ('"AI"'). The rule is checked on the call's arguments, and again on what comes back — the tool result, a resource, a prompt — so a subject that only shows up in the answer is caught too: deny withholds it, mask forces PII masking and mask.fields, warn logs, approve asks (once: not again for the answer of a call it already approved). In the LLM API gateway topic rules apply to the whole prompt, with tool: llm: ; approve refuses there, since an API call has no one to ask.

  topics:

• id: ma terms: [birleşme, "satın alma", "due diligence", acquisition, merger]
• id: salary terms: [maaş, bordro, payroll, salary] minMatches: 1 rules:
• { id: no-ma-out, match: { topic: ma, label: egress }, action: deny }
• { id: contractors, match: { topic: salary, user: "*@contractor.com" }, action: approve }
• { id: ma-to-llm, match: { topic: ma, tool: "llm:gpt-*" }, action: deny }

- **Tool exposure (`tools`):** `expose` is an allowlist of globs on the name the agent sees (absent: every tool), and `hide` removes tools after it. A hidden tool is left out of `tools/list`, so the model never reads its description (a smaller poisoning surface and fewer tokens), and a call to it is refused and counts toward `anomaly.repeatedBlocks`. `descriptions` replaces a tool's description with one you wrote; drift detection keeps watching the server's own. Unlike a `deny` rule, which refuses at call time, hiding takes the tool out of the agent's view.

• Tool poisoning at `tools/list` (`interceptors.toolPoisoning`, on by default): every definition is scanned before the agent sees it — the description (yours, when you wrote one under tools.descriptions), parameter descriptions and enum values in the input schema, and the read-only annotation. It catches instructions aimed at the model ( , "do not tell the user", "ignore previous instructions"), cross-tool shadowing ("when using the X tool, always…"), requests to read .ssh/.env, hidden zero-width, bidi and ANSI characters, words with Cyrillic or Greek lookalikes, and a readOnlyHint that the description contradicts. In block mode (default; follows promptInjection.action when unset) a tool with a critical or high finding is left out of the list and its calls are refused; medium findings (encoded blobs) only warn. Each finding is logged once as ruleId: poisoning: . The rules are the ones @guardbee/mcp-tool-poisoning-scanner uses, now shared through guard-core.
• Credentials leaving (`interceptors.egressSecrets`, on by default): before an egress tool runs, the arguments it would actually receive are checked for credentials — provider keys (AWS, GitHub, OpenAI, Anthropic, Stripe, Slack, …), private keys and connection strings with a password; the same fixed-format rules PII masking uses, never the broad keyword ones. Data taint only knows what this session's tools returned; this also catches a key the model got from the prompt, a file or its own context. block (default; follows promptInjection.action when unset) refuses the call, warn logs it; the audit event has the credential masked either way. A PII token stays a token for an egress tool unless piiMasking.detokenizeForEgress, so only then is its value checked. allowTools exempts tools by glob (a deploy tool that takes a DB URL, say). Personal data is left to PII masking and taint.
• Sampling (`interceptors.sampling`, off by default): a server can ask the agent's model for a completion (sampling/createMessage) — and a malicious one can use that to smuggle instructions to the model or pull data out. Off, the proxy does not offer sampling to servers at all. On, a request is answered only while one of that server's tool calls is running, by the session that made the call (two sessions calling the same server at once: refused, since it could belong to either); includeContext is forced to none, so a server never gets the conversation; maxTokens is capped (default 1024) and