Mcp Guardian

MCP Guardian

A safety layer between your AI assistant and the tools it uses.

[](https://www.npmjs.com/package/@mcp-guardian/server) [](https://www.npmjs.com/package/@mcp-guardian/server) [](https://badge.socket.dev/npm/package/@mcp-guardian/server/4.1.8) [](https://mcp-guardian-cloud.vercel.app/) [](https://glama.ai/mcp/servers/rudraneel93/mcp-guardian) [](https://www.typescriptlang.org/) [](https://github.com/modelcontextprotocol/typescript-sdk) [](LICENSE) [](https://github.com/rudraneel93/mcp-guardian/actions/workflows/ci.yml)

Version 4.1.8 · Website · npm · [Install & troubleshooting](docs/INSTALL.md) · [Changelog](CHANGELOG.md)

What's new in 4.1.8

• Incident policy workflow — Enterprise AI investigation drawer can generate, preview, accept, or reject blocking rules from incidents
• npm publish hardening — ordered publish script with registry dep resolution checks and clean-install verification before server goes live
• Dashboard stability — fix React hooks ordering in Security/Health panels that caused error #310 on load

What's new in 4.1.7

• Active Rules controls — Security → Policy now includes list/search, soft disable/enable, and hard delete operations synced to YAML
• Policy runtime semantics — enabled: false is honored across rule strategies with backward-compatible defaults
• Policy mutation APIs — cloud + local dashboard endpoints for list/toggle/delete with updated README guidance

What's new in 4.1.6

• mcp-guardian start — one command for proxy + web dashboard on port 4000 (local dev defaults)
• mcp-guardian setup — one-shot install for git clones (pnpm install, build, dashboard SPA)
• npm tarball — prebuilt dashboard UI (deploy/dashboard-spa/out/) built at publish time
• Install guide — expanded troubleshooting in README and [docs/INSTALL.md](docs/INSTALL.md)

What's new in 4.1.5

• npm install — fixes broken @mcp-guardian/server@4.1.4 registry manifest (workspace: deps). Use 4.1.5+.

What's new in 4.1.4

• 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
• Dashboard Agentic AI panels — PlanCompliance, Reputation, ZeroTrust, FederatedLearning, Observatory mesh sync, SandboxWizard captured-traffic scorecard, ChainGraph (A1)
• Protection home strip — roadmap compliance score on the main Protection tab with link to Agentic AI
• A1 ONNX graph path — optional fleet chain classifier via GUARDIAN_FLEET_GRAPH_ONNX_MODEL
• B3 MPC-lite masking — pairwise-masked federated gradients (GUARDIAN_FEDERATED_MPC)
• B2/B1 mesh relays — observatory and reputation mesh publish/pull; dev stub via GUARDIAN_OBSERVATORY_STUB
• Docs & env — guardian roadmap * commands documented; production env vars in .env.example

Run guardian roadmap audit --json or open Agentic AI → Overview in the dashboard to confirm 100% compliance.

What's new in 4.0.0

Industry-standard MCP protection — Guardian moves from per-call filtering to fleet-wide, cross-agent security:

• MTX v1 — open threat exchange format (@mcp-guardian/mtx) + cloud hub
• Guardian Certified MCP — HMAC attestation, persistent registry, verification API
• Multi-step attack chains — collusion detector + session-chain graph with proxy enforcement
• Capability graph & intent binding — tool/resource graph and session intent allowlists
• Agent reputation ledger — persistent scores with proxy enforcement
• Dynamic sandbox tiers — shadow / redact / allow with RL-ready persistence
• Protocol fuzzer — expanded corpus with real block validation and cert gates
• Policy simulator — /api/policy/simulate + ab_test_policy MCP tool
• Incident playbooks & AI investigator — webhook/isolate executors; Threat Lab–linked investigations
• 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](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/AGENTICROADMAP.md](docs/AGENTICROADMAP.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.

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)

1. You install Guardian and point it at your existing MCP setup (or run mcp-guardian onboard to do this automatically).
2. Guardian wraps your tool servers so the AI talks to Guardian instead of talking to them directly.
3. When the AI tries to use a tool, Guardian receives the request first.
4. Guardian compares the request to your policy (a simple rules file you control).
5. If the request is allowed, Guardian forwards it to the real tool and returns the result.
6. If the request breaks a rule, Guardian blocks it and tells the AI it was denied — the real tool never runs.
7. 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.

In this section: [System overview](#system-overview) · [Tool call path](#tool-call-path-tools_call) · [Transports](#transports) · [Agentic AI](#agentic-ai-integration) · [Dashboard](#dashboard-and-observability) · [Pro pipelines](#pro-pipeline-architecture) · [Learning loop](#continuous-improvement-loop)

System overview

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).

flowchart TB
  subgraph clients [AI clients]
    Cursor[Cursor / Cline / Claude]
  end

  subgraph guardian [MCP Guardian process]
    Proxy[Proxy layer\nstdio HTTP SSE WS streamable]
  Policy[PolicyEngine\nYAML + hot reload]
  Agentic[Agentic container\noptional hooks]
  DashboardAPI[Dashboard REST + WebSocket]
  end

  subgraph storage [Persistence]
    SQLite[(history.db)]
    SIEM[SIEM exporters\noptional]
  end

  Upstream[Upstream MCP servers\nfilesystem GitHub etc]

  Cursor --> Proxy
  Proxy --> Policy
  Proxy --> Agentic
  Policy --> Proxy
  Agentic --> Proxy
  Proxy --> Upstream
  Upstream --> Proxy
  Proxy --> SQLite
  Proxy --> SIEM
  DashboardAPI --> SQLite
  clients -.-> DashboardAPI

| Component | Role | Main code | |-----------|------|-----------| | Proxy layer | Intercepts JSON-RPC; enforces policy on every tools/call | [src/proxy/](src/proxy/) | | Policy engine | Evaluates YAML rules, rate limits, RBAC, patterns | [src/policy/](src/policy/) | | History DB | Stores allow/block audit, tokens, cost | [src/database/history-db.ts](src/database/history-db.ts) | | Dashboard | Local UI + REST API over the same DB | [deploy/dashboard-spa/](deploy/dashboard-spa/), [src/utils/dashboard-server.ts](src/utils/dashboard-server.ts) | | Agentic | Smart features (injection scan, policy gen, trust, etc.) | [src/agentic/](src/agentic/) |

Enterprise deployments may add Redis (rate limits, DPoP, circuit-breaker sync) and PostgreSQL instead of SQLite — see [ENTERPRISEDEPLOYMENT.md](docs/ENTERPRISEDEPLOYMENT.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:

1. Pre-forward guard ([src/proxy/tool-call-pre-guard.ts](src/proxy/tool-call-pre-guard.ts)) — caps expanded argument size and runs agentic pre-hooks (prompt injection, etc.) on all transports.
2. Policy ([src/policy/policy-engine.ts](src/policy/policy-engine.ts)) — your YAML rules; rate-limit counters survive hot-reload via [src/policy/rate-limit-store.ts](src/policy/rate-limit-store.ts).
3. Semantic gate ([src/proxy/proxy-post-policy-gates.ts](src/proxy/proxy-post-policy-gates.ts)) — optional LLM/heuristic check on arguments before forward.
4. Audit — [persistCallRecord](src/utils/call-record-cost.ts) → async [audit-write-queue](src/database/audit-write-queue.ts) → SQLite; blocks also emit [StructuredLogger.logBlocked](src/utils/structured-logger.ts) for SIEM.

Transports

Guardian implements the same governance stack on every MCP transport your IDE might use:

| Transport | Entry module | tools/call governance | |-----------|--------------|-------------------------| | stdio | [src/proxy/proxy-server.ts](src/proxy/proxy-server.ts) | Full pipeline (default for wrapped configs) | | HTTP | [src/proxy/http-proxy-server.ts](src/proxy/http-proxy-server.ts) | Full + pre-forward guard | | SSE | [src/proxy/sse-proxy-server.ts](src/proxy/sse-proxy-server.ts) | Full + pre-forward guard | | WebSocket | [src/proxy/websocket-proxy-server.ts](src/proxy/websocket-proxy-server.ts) | Full + pre-forward guard | | Streamable HTTP | [src/proxy/streamable-http-proxy-server.ts](src/proxy/streamable-http-proxy-server.ts) | Full + pre-forward guard |

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](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

| Integration point | What happens | |-------------------|--------------| | Every tools/call | [runAgenticPreForwardHooks](src/agentic/proxy-integration.ts) can block or sanitize arguments when agentic mode is on | | MCP tools | ~35 agentic tools registered in [src/index.ts](src/index.ts) for automation and dashboard actions | | Modules | 40+ agentic modules in [src/agentic/](src/agentic/) (prediction, policy-gen, mesh, collusion, reputation, etc.) | | Dashboard | Agentic AI workspace reads [/api/agentic/*](src/utils/agentic-dashboard-summary.ts) summaries | | Database | Agentic state in [011-agentic-tables.sql](src/database/migrations/011-agentic-tables.sql) |

Module-level detail: [docs/AGENTICARCHITECTURE.md](docs/AGENTICARCHITECTURE.md) · Shipped features: [docs/AGENTICFEATURES.md](docs/AGENTICFEATURES.md) · Roadmap: [docs/AGENTICROADMAP.md](docs/AGENTICROADMAP.md).

Dashboard and observability

flowchart LR
  Proxy[Proxy w

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [rudraneel93](https://github.com/rudraneel93)
- **Source:** [rudraneel93/mcp-guardian](https://github.com/rudraneel93/mcp-guardian)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/@mcp-guardian/server

Install and usage instructions live in the source repository linked above.