Security, cost, and health governance proxy for MCP infrastructure
MCP Guardian (io.github.rudraneel93/mcp-guardian)
MCP Guardian is a governance proxy for Model Context Protocol (MCP) infrastructure focused on security, cost, and health. It positions itself as a “safety layer” between an AI assistant and the tools the assistant uses, and is distributed as an npm package (@mcp-guardian/server).
🛠️ Key Features
Security governance for MCP infrastructure
Cost governance
Health governance
Operates as a proxy (“safety layer” between assistant and tools)
🚀 Use Cases
Applying security controls to MCP tool usage
Governing operational concerns (cost and health) for MCP-based systems
Implementing a proxy-based approach for MCP infrastructure governance
⚡ Developer Benefits
Uses the MCP ecosystem (“mcp” / “model-context-protocol”)
Provides governance tooling aligned with infrastructure and observability topics
mcp-guardian onboard from global npm — resolves the installed package root (not cwd); writes guardian-configs/ under your current directory; ships scripts/guardian-proxy.sh and policy-audit.yaml in the npm tarball
What's new in 4.1.3
npm install fix — registry manifest now matches published tarballs (^4.1.3 semver deps, not workspace:). Use @mcp-guardian/server@4.1.3 or later. Publish via ./scripts/publish-npm-all.sh (server/CLI ship from .tgz so metadata stays correct).
What's new in 4.1.1
npm install hygiene — fixes supply-chain scanner findings from 4.1.0:
Published tarballs no longer include postinstall or other lifecycle scripts
workspace: dependencies are rewritten to semver (^4.1.1) at pack time
Publish all packages via ./scripts/publish-npm-all.sh (core → plugin-sdk → server → cli)
What's new in 4.1.0
Industry roadmap plan compliance — runtime verification and dashboard wiring for all eleven fleet-wide modules (A1–C5, B1–B3):
guardian roadmap audit — CLI + GET /api/agentic/plan-compliance/audit verify every shipped module; exit 0 when production-ready
Compliance evidence runner — live policy + audit wired to SOC2/HIPAA/PCI/FedRAMP/ISO mappings
guardian-bench — mcp-guardian bench CLI + public leaderboard
See CHANGELOG.md for 3.4.1 production hardening (JWKS refresh, payload limits, SIEM on all block paths, audit retention).
Roadmap (shipped in 4.0): Semantic policy translator with approval flows, config provenance chain, STRIDE/LINDDUN threat modeling, behavioral biometrics, cross-MCP attack chains with SIEM export, digital twin sandbox, zero-trust SPIFFE scoring, decentralized reputation network, ecosystem observatory, insurance risk quantification + PDF export, and federated threat detection — docs/AGENTIC_ROADMAP.md.
Fleet mandate for CISO buyers
Guardian v4 is designed as a fleet-wide control plane, not a single-proxy filter:
Mandatory policy provenance — every YAML change is hash-chained, signed, and exportable to SIEM/auditors
Human-in-the-loop policy approval — NL drafts must pass simulation + explicit approval before apply
Cross-agent attack chain detection — session graphs span servers; alerts export as CEF for Splunk/Datadog
SPIFFE/mTLS identity — zero-trust composite scores include workload identity from SPIFFE SVIDs
Cloud observatory + reputation mesh — anonymized fleet telemetry and server reputation consensus via MCP Guardian Cloud
Insurance-ready risk reports — ALE quantification with underwriter PDF export for cyber insurance workflows
What problem does this solve?
Modern AI assistants (Claude, Cursor, Cline, and others) can connect to tools — read files, run commands, query databases, post to Slack, and more. Those connections often use a standard called MCP (Model Context Protocol).
That power is useful, but risky:
The AI might read files it should not see.
It might run shell commands or delete data by mistake or because of a malicious prompt.
Secrets can leak through tool arguments.
API costs can spike without you noticing.
MCP Guardian sits in the middle. Every tool request goes through Guardian first. Guardian checks your rules, blocks bad requests, logs what happened, and can show you a live dashboard — before anything reaches your real tools.
code
Your AI assistant
│
▼
MCP Guardian ← reads your rules, blocks bad calls, keeps a log
│
▼
Your real tools (files, GitHub, database, …)
How it works (step by step)
You install Guardian and point it at your existing MCP setup (or run mcp-guardian onboard to do this automatically).
Guardian wraps your tool servers so the AI talks to Guardian instead of talking to them directly.
When the AI tries to use a tool, Guardian receives the request first.
Guardian compares the request to your policy (a simple rules file you control).
If the request is allowed, Guardian forwards it to the real tool and returns the result.
If the request breaks a rule, Guardian blocks it and tells the AI it was denied — the real tool never runs.
Every allow and block is saved to a local database so you can review history and see charts on the dashboard.
You stay in control: Guardian does not silently change your rules unless you approve it (for example when reviewing Threat Lab suggestions).
Architecture
This section shows how MCP Guardian is wired together: what runs where, how a tool call flows through governance, and how optional Pro pipelines connect to the proxy.
When you run mcp-guardian start or pnpm dashboard:proxy, one Node process typically hosts the policy proxy, the dashboard API, and (optionally) agentic services. All components share the same audit database (MCP_GUARDIAN_DB_PATH, default ~/.mcp-guardian/history.db).
Enterprise deployments may add Redis (rate limits, DPoP, circuit-breaker sync) and PostgreSQL instead of SQLite — see ENTERPRISE_DEPLOYMENT.md.
Tool call path (tools/call)
Every dangerous decision happens before the real MCP server runs. If Guardian blocks a call, the upstream tool never receives it.
sequenceDiagram
participant Client as AI client
participant Transport as Proxy transport
participant PreGuard as Pre-forward guard
participant Policy as PolicyEngine
participant Semantic as Semantic gate
participant Upstream as Upstream MCP
participant Audit as Audit queue
participant SIEM as SIEM log
Client->>Transport: tools/call JSON-RPC
Transport->>PreGuard: checkExpandedPayload + agentic hooks
alt blocked at pre-guard
PreGuard-->>Client: JSON-RPC error -32001
PreGuard->>Audit: denied record
PreGuard->>SIEM: tool_blocked
else allowed
PreGuard->>Policy: evaluateAsync context
alt policy block
Policy-->>Client: JSON-RPC error
Policy->>Audit: denied record
Policy->>SIEM: tool_blocked
else policy pass
Policy->>Semantic: sync semantic request gate
alt semantic block
Semantic-->>Client: JSON-RPC error
Semantic->>Audit: denied record
Semantic->>SIEM: tool_blocked
else forward
Semantic->>Upstream: forward request
Upstream-->>Transport: tool result
Transport->>Transport: response DLP gate
Transport-->>Client: JSON-RPC result
Transport->>Audit: allow record
end
end
end
Integration details:
Pre-forward guard (src/proxy/tool-call-pre-guard.ts) — caps expanded argument size and runs agentic pre-hooks (prompt injection, etc.) on all transports.
Run mcp-guardian onboard so client configs point at Guardian-wrapped servers. If an IDE connects to an MCP server around Guardian (common with raw SSE URLs), calls are untracked — metrics and logs will show sse_untracked.
Agentic AI integration
Agentic features are optional modules loaded at boot (src/container.ts). They do not replace your YAML policy; they add observation, scoring, and recommendations.
flowchart TB
subgraph mcp [MCP surface]
Tools[MCP tools in src/index.ts]
end
subgraph container [DI container]
Core[agentic/core.ts\npipeline scheduler telemetry]
Features[Feature modules\npolicy gen injection trust mesh]
end
subgraph runtime [Runtime integration]
Hooks[proxy-integration.ts\npre/post call hooks]
PreGuard[tool-call-pre-guard.ts]
end
subgraph ui [Dashboard]
API[agentic-dashboard-summary.ts]
Workspace[Agentic AI workspace SPA]
end
DB[(agentic tables\nmigration 011)]
Tools --> Core
Core --> Features
PreGuard --> Hooks
Hooks --> Features
API --> DB
Workspace --> API
Hooks --> DB
The dashboard is not a separate database — it reads the same call_records the proxy writes. Set MCP_GUARDIAN_DB_PATH consistently when running pnpm real-life:filesystem or other tests so charts match proxy traffic.
Pro pipeline architecture
These Pro workflows run alongside the live proxy. They consume audit data, swarm reports, and LLM output to improve detection — they do not sit in the hot path of every tool call.
Security Swarm
Automated red-team loop: generate attacks, run the harness, detect bypasses, feed learning.
What it does: Runs scripted steps (build, corpus eval, parity, harness) and records bypasses when policy allows an attack that should be blocked.
How it connects: Reads/writes under reports/security-swarm/; bypasses and proposals can inform Threat Lab and runtime attack-learning.
Run:pnpm security-swarm (Pro license in production).
Threat Lab (LLM discovery)
Human-reviewed LLM proposals for new attack fixtures and policy ideas.
What it does: Collects signals (bypasses, semantic TPs, ThreatIntel), asks a local LLM for new corpus candidates, validates them, writes threat-lab-candidates.json for you to accept.
How it connects: Outputs feed the adversarial harness and optional policy-applier after review — nothing is applied silently.
Run:pnpm security-swarm:threat-lab (requires Ollama). See THREAT_LAB.md.
Auto Threat Research
Background LLM research when the proxy blocks suspicious traffic; writes validated adv-*.json fixtures.
What it does: Debounces block events, classifies attack types, writes harness fixtures when validation passes (dedupe + rate caps).
How it connects: Uses the same auto-corpus writer as Threat Lab when both GUARDIAN_THREAT_RESEARCH_AUTO and SWARM_THREAT_RESEARCH_AUTO are enabled.
Run: Enable env flags on the proxy host; or trigger from dashboard Threat Discovery.
Below is what each major capability does, in plain language.
Policy proxy (the core)
What it is: A filter on every tool call.
How it works: You write rules in a YAML file (see The policy file below). Rules can allow specific tools, deny dangerous ones, limit how often tools run, cap token usage, and match patterns in arguments (for example “block if the path contains ../”). When you change the file, Guardian can reload rules without restarting.
Why it matters: This is your main line of defense — fast, predictable, and fully under your control.
Attack blocking (built into the default policy)
What it is: Hundreds of pre-written checks for common abuse.
How it works: Before a call reaches your server, Guardian looks for things like shell commands hidden in arguments, path traversal (../etc/passwd), SQL injection patterns, attempts to exfiltrate secrets, suspicious URLs, and Unicode tricks that hide malicious text. If a pattern matches, the call is blocked and logged.
Why it matters: Many real-world attacks look like normal tool calls; these checks catch a large class of them without an AI model.
Cost tracking
What it is: A running tally of how much your tool usage costs.
How it works: Guardian estimates tokens and dollar cost per call (using model pricing when available). You can set budgets and see burn rate over time in the dashboard.
Why it matters: Runaway agents or loops can get expensive; you see it early.
Health monitoring
What it is: A health check for each connected MCP server.
How it works: Guardian tracks success rate, latency, and whether a server is responding. If a server keeps failing, a circuit breaker can stop hammering it.
Why it matters: You notice broken or flaky integrations before users complain.
Live audit log
What it is: A permanent record of what was allowed and what was blocked.
How it works: Each decision is stored in a local SQLite database (default: ~/.mcp-guardian/history.db). The dashboard reads this database to show tables, charts, and filters.
Why it matters: Security and debugging need a clear trail — who tried what, when, and why it was blocked.
Package scanning (CVE and typo-squat)
What it is: A check on MCP packages before you trust them.
How it works: Guardian can scan installed or configured packages for known security issues (CVEs) and names that look like famous packages but are slightly misspelled (typo-squatting).
Why it matters: Supply-chain attacks often arrive as “almost the right” package name.
Adversarial harness (offline tests)
What it is: A large automated test suite that fires attack-like requests at your policy without a live AI.
How it works: Run pnpm harness from the repo. It replays 800+ fixtures and reports what would be blocked or allowed.
Why it matters: You can change rules and immediately see if you broke legitimate use or left a hole open.
Real-life scenarios (live tests)
What it is: A short or long run of real attack traffic against a real filesystem MCP server through Guardian.
How it works: Commands like pnpm real-life:filesystem drive the official filesystem server with path traversal, injection, and similar tests while the proxy is running. Results show up in the dashboard if you use the same database path.
Why it matters: Offline tests are fast; live tests prove the full path (proxy → policy → log → UI) works.
Agentic AI features (version 4.1)
These are smart assistants inside Guardian that watch, score, and recommend — they do not replace your policy unless you choose to apply a suggestion.
Shipped today
Feature
What it does for you
Threat prediction
Scores how risky each MCP server is and suggests hardening before something breaks.
Policy generation
Watches normal tool use, then drafts a tight “only what you actually need” policy you can review.
Prompt injection detection
Scans tool arguments for text meant to hijack another AI (heuristic + optional LLM).
Threat mesh (MTX)
Opt-in anonymized attack-pattern sharing; @mcp-guardian/mtx open exchange format.
Persistent reputation ledger with proxy enforcement.
Sandbox tiers
Dynamic shadow / redact / allow per tool or server.
Guardian Certified MCP
HMAC-signed server attestation and verification tiers.
Policy simulator
Preview policy impact before deploy (ab_test_policy, REST simulate API).
Incident playbooks & investigator
Automated playbook steps; AI incident investigation in the dashboard.
MCP lifecycle guard
Session-gated access to tools/list, resources/read, prompts/get.
Response DLP
Scans upstream tool responses and streaming output for secrets.
RL tuning
Contextual bandits and Thompson sampling for threshold optimization.
Dashboard: Open Agentic AI in the web UI for overview charts, trust scores, audit tables, and admin tools. See Agentic Features Guide.
Industry-standard roadmap (shipped in 4.0)
Guardian’s industry-standard layer delivers cross-server, cross-agent, systemic protection — what enterprise CISOs need to mandate Guardian fleet-wide. All eleven capabilities shipped in v4.0:
Full detail, foundations already in code, and differentiation rationale: docs/AGENTIC_ROADMAP.md.
Verify compliance: Run guardian roadmap audit (or --json for machine-readable output). The dashboard Agentic AI → Overview tab shows the same runtime audit via Industry Roadmap Compliance. Additional CLI utilities: guardian roadmap fleet-graph-train, federated-export|import, observatory-sync, reputation-sync. See Agentic Quickstart.
Production env vars (optional): fleet chain blocking (GUARDIAN_FLEET_CHAIN_BLOCK_CONFIDENCE), multi-region Redis (GUARDIAN_FLEET_REGION), observatory relay or dev stub (GUARDIAN_OBSERVATORY_RELAY_URL, GUARDIAN_OBSERVATORY_STUB), federated learning (GUARDIAN_FEDERATED_LEARNING, GUARDIAN_FEDERATED_MPC), ONNX graph model (GUARDIAN_FLEET_GRAPH_ONNX_MODEL). Full list in .env.example.
The web dashboard
What it is: A local website (default http://localhost:4000) that shows what Guardian is doing.
How it works: When you run mcp-guardian start (or pnpm dashboard:proxy from a git clone), the same process serves the dashboard and the API. The UI reads real data from your history database — not fake demo numbers.
Main areas:
Area
What you see
Protection
Overall status and plain-English analysis of your setup.
Activity
Audit log of allowed and blocked calls.
Threats
Active threats and quarantine actions.
Security
Security score and trends.
Operations
Traffic, errors, and cost charts over time.
Agentic AI
Autonomous features: trust, threats, policy, operations, audit, and tools. Industry roadmap panels (A1–C5, B1–B3) live here — plan compliance audit on Overview.
Settings
Servers, policy, and setup checklist.
Tip: If charts say “no traffic in this time window,” widen the Time window dropdown (for example Last 7 days). Short windows only show very recent calls.
Security Swarm (Pro)
What it is: A team of automated testers that keep trying to break your policy the way an attacker would.
How it works:
One track generates and runs attacks, checks for bypasses, and writes reports.
Another track learns from real blocks on your proxy and improves detection over time.
The two tracks feed each other so tests get better as your deployment sees real traffic.
Why it matters: Your policy is only as strong as the attacks you have tested against; the swarm expands that set continuously.
Run: pnpm security-swarm (license required in production). Architecture diagram: Architecture § Pro pipeline above.
Threat Lab (Pro)
What it is: Uses a local AI model to propose new attack patterns and rule ideas based on what Guardian has seen.
How it works:
Collects signals from recent blocks, CVE data, and swarm findings.
The model suggests new test cases and possible policy lines.
Automated checks validate proposals.
You review and approve — nothing is applied automatically.
Run: pnpm security-swarm:threat-lab (needs Ollama or another configured LLM). See THREAT_LAB.md.
Auto Threat Research (Pro)
What it is: Background research when something interesting is blocked.
How it works: When the proxy blocks a suspicious call, events can be queued, grouped, and analyzed by an LLM to classify the attack type and add it to your research corpus. It does not change your live policy by itself — it builds knowledge for you to use later.
Enable with GUARDIAN_THREAT_RESEARCH_AUTO=true when licensed.
Guardian Autopilot (Pro)
What it is: One-command setup: wrap MCP configs, start the proxy, turn on the dashboard, and optional background services (digests, learning).
Local development can use GUARDIAN_CI_BYPASS_LICENSE=true with pnpm dashboard:proxy. Production Pro needs a license — PRO_SETUP.md.
Getting started — install, clone, and run
This section walks through every path to a working Guardian: npm install for day-to-day use, git clone for development, and mcp-guardian start (or pnpm dashboard:proxy from the repo) to run the proxy + web dashboard together on port 4000.
npm note:mcp-guardian start, setup, and onboard --start ship in 4.1.6 on GitHub. If mcp-guardian start is missing from help, your global install is older than 4.1.6 — use git clone + build below, or npm install -g @mcp-guardian/server@4.1.6 once published. Full fixes: docs/INSTALL.md.
What you need
Requirement
Notes
Node.js 18+
Required by @mcp-guardian/server
npm
For global install or running the published CLI
pnpm
Only if you develop from a git clone (pnpm install, pnpm build)
Git
Only for clone-from-source workflow
Ollama (optional)
Local LLM at http://127.0.0.1:11434 for semantic detection, Threat Lab, and Auto Threat Research in dev
Install from npm (recommended for users)
Install the published server package. Pin 4.1.5+ — older 4.1.1–4.1.4 releases had broken workspace: metadata on npm. 4.1.6 adds start / setup (see GitHub master or npm once published).
bash
# Global CLI (mcp-guardian command on your PATH)
npm install -g @mcp-guardian/server@latest
# Or install in a project directory
npm install @mcp-guardian/server@latest
Verify the CLI and install health:
bash
mcp-guardian --version
mcp-guardian doctor
What you get: compiled dist/, default policy templates, prebuilt dashboard static files (deploy/dashboard-spa/out/ in 4.1.6+), and the mcp-guardian CLI (start, onboard, proxy, analyze, doctor, etc.).
Recommended flow after install:
bash
mcp-guardian onboard --apply
mcp-guardian start
Open http://localhost:4000. Or combine: mcp-guardian onboard --apply --start (4.1.6+).
Manual proxy (advanced) — only if you need custom env vars without start:
Primary command (npm global or git clone, 4.1.6+):
bash
mcp-guardian start
Sets local defaults (DASHBOARD_ENABLED, MCP_GUARDIAN_DB_PATH=~/.mcp-guardian/history.db, license bypass for localhost), picks a single-server guardian-configs/*.json (or onboard configsDir), and runs proxy + API + UI.
Open the browser → Protection, Activity, Agentic AI, etc. If charts are empty, widen the time window (e.g. Last 7 days) or generate traffic (next section).
Stop:Ctrl+C in the terminal. If port 4000 is stuck: lsof -ti :4000 | xargs kill.
Dashboard UI development (hot reload)
When editing React panels under deploy/dashboard-spa/, run the SPA dev server separately:
bash
# Terminal 1 — proxy + API (backend)
pnpm dashboard:proxy
# Terminal 2 — Next.js dev server for the SPA (frontend hot reload)
pnpm dashboard:dev
For SOC-style split API + UI: pnpm soc:full (API on 4040, SPA dev server — see package.json).
Easiest path: onboard (wrap your AI client)
After npm global install (4.1.6+), let Guardian find and wrap MCP configs for Cursor, Claude Desktop, Cline, and Windsurf:
bash
mcp-guardian onboard --apply
mcp-guardian start
--apply patches your live IDE MCP JSON (with backup). Restart your AI client so traffic flows through Guardian.
If you see “No MCP config found for client auto”:
Install and configure an IDE with MCP first (Cursor, Cline, Claude Desktop, or Windsurf), or
Pass a client: mcp-guardian onboard --client cursor --apply, or
Pass a config file: mcp-guardian onboard --config /path/to/mcp.json --apply, or
Skip onboard and start with a repo example: mcp-guardian start --config guardian-configs/filesystem.json
Without DASHBOARD_ENABLED, you get proxy-only (no web UI). Logs still go to MCP_GUARDIAN_DB_PATH.
Generate test traffic and verify
With mcp-guardian start or pnpm dashboard:proxy running in one terminal:
bash
# Same DB as the proxy (important for dashboard charts)export MCP_GUARDIAN_DB_PATH="${MCP_GUARDIAN_DB_PATH:-$HOME/.mcp-guardian/history.db}"# Short live attack smoke test against the official filesystem MCP server
pnpm real-life:filesystem
# Offline policy matrix (no live MCP server required)
pnpm harness
# Plain-English summary of current posture
pnpm analyze
# Industry roadmap module audit (CLI)
node dist/cli.js roadmap audit
# or after global install: mcp-guardian roadmap audit
Global install is older than 4.1.6. git pull && pnpm build && node dist/cli.js start, or npm install -g @mcp-guardian/server@latest when 4.1.6 is on npm
unknown option --start
Same — upgrade to 4.1.6 or run onboard --apply then start separately
InstallError / workspace: on npm
Use @mcp-guardian/server@4.1.5+, not 4.1.1–4.1.4; npm cache clean --force then reinstall
ETARGET / No matching version for @mcp-guardian/core
Publish chain incomplete — maintainers run ./scripts/publish-npm-all.sh
next: command not found (dashboard build)
npm: reinstall package (prebuilt out/ in 4.1.6). Git: mcp-guardian setup or cd deploy/dashboard-spa && npm install && npm run build
benchmark-report.json missing`
git pull — seed file must exist under deploy/dashboard-spa/app/data/
pnpm dashboard:proxy not found
Run from repo root, or use mcp-guardian start globally
No MCP config found
mcp-guardian onboard --apply or mcp-guardian start --config guardian-configs/filesystem.json
The bundled default policy already blocks many common attack patterns. You can extend it or start from templates in policy-templates/. Full reference: POLICY.md.
Settings you might change
Variable
Plain meaning
MCP_GUARDIAN_POLICY
Path to your rules file
MCP_GUARDIAN_DB_PATH
Where call history is stored (share this between proxy and test runners)
MCP_GUARDIAN_RETENTION_DAYS
How long to keep audit rows (default 30)
MCP_GUARDIAN_MAX_PAYLOAD_BYTES
Max raw JSON-RPC message size (default 10MB)
GUARDIAN_MAX_EXPANDED_PAYLOAD_BYTES
Max serialized tool-argument size after decode (default 50MB)
GUARDIAN_JWKS_REFRESH_MS
How often to refresh OIDC JWKS (default 5 minutes)
GUARDIAN_STRICT_ALLOWLIST_RBAC
Require RBAC on tools.allow policy rules
GUARDIAN_HEALTH_PROBE_INTERVAL_MS
Periodic MCP health probes (0 = disabled)
GUARDIAN_SHUTDOWN_GRACE_MS
Wait for in-flight calls on shutdown (default 30s)
GUARDIAN_DB_ENCRYPTION_KEY
Encrypt sensitive audit fields at rest
GUARDIAN_DB_ENCRYPT_AUDIT_ARGS
Also encrypt redacted argument snippets in audit (true + key above)
MCP_GUARDIAN_SIEM_ENABLED
Export block/audit events to Splunk, Datadog, webhooks, etc.
