# Mcp Guardian

> Security, cost, and health governance proxy for MCP infrastructure — YAML policy engine, OAuth 2.1/OIDC, web dashboard, mTLS, semantic shell analysis, STRIDE threat model

- **Type:** MCP server
- **Install:** `agentstack add mcp-rudraneel93-mcp-guardian`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [rudraneel93](https://agentstack.voostack.com/s/rudraneel93)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [rudraneel93](https://github.com/rudraneel93)
- **Source:** https://github.com/rudraneel93/mcp-guardian
- **Website:** https://www.npmjs.com/package/@mcp-guardian/server

## Install

```sh
agentstack add mcp-rudraneel93-mcp-guardian
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://mcp-guardian-cloud.vercel.app) · [npm](https://www.npmjs.com/package/@mcp-guardian/server) · [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/AGENTIC_ROADMAP.md](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.

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

```mermaid
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 [ENTERPRISE_DEPLOYMENT.md](docs/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.

```mermaid
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.

```mermaid
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/AGENTIC_ARCHITECTURE.md](docs/AGENTIC_ARCHITECTURE.md) · Shipped features: [docs/AGENTIC_FEATURES.md](docs/AGENTIC_FEATURES.md) · **Roadmap:** [docs/AGENTIC_ROADMAP.md](docs/AGENTIC_ROADMAP.md).

### Dashboard and observability

```mermaid
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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-rudraneel93-mcp-guardian
- Seller: https://agentstack.voostack.com/s/rudraneel93
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.