🛡️ MCP Guardian

Runtime security, cost governance, and health monitoring proxy for MCP infrastructure.

MCP Guardian sits between AI agents and MCP servers, enforcing active security policies, tracking real token costs, monitoring server health, and providing enterprise observability — all through a YAML-configurable engine with hot-reload.

It works as a transparent proxy, a standalone CLI, an MCP server (so agents can self-audit), and a pnpm monorepo — install only what you need.

Quick Start

# Install globally
npm install -g @mcp-guardian/server

# Scan your MCP servers for CVEs, secrets, and injection attacks
mcp-guardian scan --all

# Proxy with active policy enforcement
mcp-guardian proxy --policy ./default-policy.yaml --blocking-mode block

# Generate a full security-cost-health report
mcp-guardian report --all --format markdown --output guardian-report.md

# Run as an MCP server (AI agents can self-audit)
mcp-guardian       # stdio transport, auto-starts MCP server

Features

Security

• Three-layer detection engine — Regex triage (38 patterns, 8 attack categories) → Schema analysis (parameters, defaults, enum injection) → LLM semantic verdict (Anthropic Claude), with semantic layer defaulting to run on all tools for comprehensive coverage

• YAML policy engine — Tool allowlists/denylists, regex patterns, rate limits, token budgets, RBAC, argument-level field patterns, destructive category detection, and default-deny (fail-closed) catch-all

• Hot-reload policies — File watcher atomically swaps policy engine on YAML changes — zero-downtime policy updates

• 50+ secret patterns — OpenAI, Anthropic, GitHub, AWS, GCP, Azure, Stripe, Slack, Twilio, SendGrid, Datadog, CircleCI, Jenkins, Firebase, Cloudflare, HuggingFace, GitLab, NPM, Vercel, Heroku, database connection strings, RSA/PEM private keys, JWT secrets, and URI credentials

• Shannon entropy analysis — Detects base64/hex-encoded secrets that regex patterns miss, with configurable allowlist

• AST command validation — Shell-quote-based tokenizer with 33 dangerous commands, 6 structural operators, 5 suspicious path patterns, and Unicode homoglyph normalization (Cyrillic, fullwidth, zero-width attacks)

• CVE scanning — OSV.dev + NVD with transitive dependency tree scanning (200+ packages), direct/transitive triage, and LRU result caching

• Response inspection — Prompt injection and data exfiltration detection in tool responses

• Hardcoded secret detection — Scans adjacent .env files, docker-compose.yml, and environment variables

• Typo-squatting detection — Levenshtein distance analysis against known MCP server names

• Auth weakness probing — Missing authentication, unencrypted transport detection

Authentication & Zero Trust

• OAuth 2.1 / OIDC — JWT validation with OIDC Discovery, algorithm pinning (RS256/384/512, ES256/384, PS256 — rejects alg: none confusion attacks), audience/issuer validation, agent identity extraction

• DPoP — RFC 9449 sender-constrained tokens for replay-proof authentication

• RBAC — Scope-based and client-ID-based access control in policy engine

• mTLS — Mutual TLS with client certificates for proxy ↔ upstream communication

• Dashboard authentication — JWT session tokens, API key auth, CSRF protection, rate-limited login

Cost Governance

• Real token counting — Proxy intercepts tools/call traffic and counts tokens via tiktoken (o200k_base for OpenAI, char-ratio estimates for Anthropic/Google/DeepSeek/Meta/Mistral)

• 17 providers, 2,138 models — Live pricing via litellm, with per-model cost comparison

• Cost efficiency scoring — Weighted 3-way composite score: security (40%), health (30%), cost efficiency (30%)

• Per-tool breakdown — Tokens, duration, and estimated cost for every intercepted call

Health & Observability

• Live JSON-RPC probes — Latency, success rate, tool count, and context pressure

• Circuit breaker — 3-state pattern (CLOSED, OPEN, HALF_OPEN) protects upstream servers from cascading failures

• Prometheus metrics — Counters (requests, blocked, auth failures), gauges (circuit breaker state, active sessions), histograms (proxy latency, auth latency)

• /healthz and /readyz endpoints — Liveness and readiness probes for K8s deployment

• WebSocket dashboard — Real-time push broadcaster replacing 5s polling, with graceful fallback

• OpenTelemetry — Distributed tracing across proxy and MCP servers via OTLP

• Structured logging — pino with request-ID tracing, policy decision audit trails

• Webhook alerting — Slack and Discord webhook support for critical policy events with severity filtering

Architecture

• pnpm monorepo — packages/core (detection engine), packages/cli, packages/server (MCP server), plus root src/ (proxy, scanners, services, policy, auth)

• better-sqlite3 — Native, WAL-mode, crash-safe database with advisory file locking (prevents multi-instance corruption), versioned migrations, automated purge, and prepared statements

• Dependency injection interfaces — IHistoryDb, ISecurityScanner, ICostAuditor, IHealthMonitor, IPolicyEngine for testability and swappable implementations

• Secret provider interface — Pluggable secret backends: EnvSecretProvider (default), HashiCorpVaultProvider, AwsSecretsManagerProvider

• Redis cluster-state enforcement — Warns on multi-replica/K8s without Redis; GUARDIAN_STRICT_MODE=true refuses startup

• Graceful shutdown — Async hook system flushes DB, closes connections, and WAL-checkpoints before exit

Deployment

• Helm chart — K8s Deployment with liveness/readiness probes, resource limits, security context (non-root, read-only filesystem, dropped capabilities), NetworkPolicy (ingress/egress rules, CIDR-based dashboard access), and ExternalSecrets support

• Helm release workflow — GitHub Actions auto-publishes chart to gh-pages on tagged releases

• Docker — Multi-stage build with production-ready image

• Supply chain CI — npm audit, CycloneDX SBOM generation, npm provenance attestation

Testing & Quality

• 33 tests across 3 packages (core: 12, server: 12, cli: 9)

• Code coverage — 80% lines, 80% functions, 75% branches enforced in CI

• E2E proxy tests — Real proxy spawns with policy YAML, sends JSON-RPC, verifies block/pass decisions

• Fuzz testing — Payload normalizer and policy engine fuzzing

• Red-team corpus — Labeled poisoned/benign test cases with precision/recall measurement

Installation

# Global CLI
npm install -g @mcp-guardian/server

# As an MCP server (for AI assistant integration)
npx @mcp-guardian/server

# From source (monorepo)
git clone https://github.com/rudraneel93/mcp-guardian.git
cd mcp-guardian
pnpm install
pnpm build
pnpm start

CLI Reference

mcp-guardian scan

mcp-guardian scan --all                          # Scan all discoverable MCP configs
mcp-guardian scan --config ./mcp.json             # Scan a specific config
mcp-guardian scan --fail-on-critical              # Exit 1 if any CRITICAL CVE found
mcp-guardian scan --fail-on-secrets               # Exit 1 if any hardcoded secret found
mcp-guardian scan --threshold-score 60            # Exit 2 if any server scores below 60

Outputs per-server CVE list, auth status, typo-squat risk, secrets found, and composite security score (0–100).

mcp-guardian audit

mcp-guardian audit --all                          # Audit costs for all servers
mcp-guardian audit --server github                 # Filter to a specific server
mcp-guardian audit --threshold-cost 0.01           # Exit 2 if total cost exceeds $0.01

Outputs per-server token usage, estimated cost (USD), and tool-level breakdown.

mcp-guardian health

mcp-guardian health --all                          # Health-check all servers
mcp-guardian health --fail-on-overload              # Exit 1 if any server has tool overload
mcp-guardian health --threshold-latency 1000        # Exit 2 if latency exceeds 1000ms

Outputs per-server latency, success rate, tool count, and overload warnings.

mcp-guardian report

mcp-guardian report --all                          # Full security-cost-health report
mcp-guardian report --format markdown              # Output as markdown
mcp-guardian report --format json                  # Output as JSON
mcp-guardian report --output guardian-report.md    # Write to file
mcp-guardian report --threshold-score 75           # Exit 2 if overall score below 75

Generates a comprehensive report with overall score (weighted: security 40%, health 30%, cost efficiency 30%).

mcp-guardian proxy

mcp-guardian proxy --config ./mcp.json --policy ./default-policy.yaml --blocking-mode block
mcp-guardian proxy --policy ./policy.yaml --dry-run          # Simulate without activating
mcp-guardian proxy --auth-issuer https://accounts.google.com --auth-audience my-app
mcp-guardian proxy --auth-required                            # Fail-closed auth

Starts the transparent proxy. Policy modes: audit (passive), warn (flag only), block (active enforcement). With --dry-run, evaluates policy against historical call records without activating the proxy.

Policy Engine

Policies are YAML files evaluated against every tools/call in real time. The pipeline normalizes payloads (decoding hex/unicode/URL/HTML entity obfuscation), performs semantic shell analysis, then evaluates rules in order.

# default-policy.yaml
version: '1.0'
policy:
  mode: block
  default_action: block       # fail-closed — blocks anything not explicitly allowed

  rules:
    - name: block-shell-injection
      action: block
      patterns:
        - curl\s|wget\s
        - rm\s+-rf
        - ;\s*\w
        - '&&|\|\|'
        - \$\{
        - '`[^`]+`'
        - /etc/passwd|/etc/shadow

    - name: deny-dangerous-tools
      action: block
      tools:
        deny:
          - execute_command
          - bash
          - sh
          - eval
          - exec
          - system
          - spawn
          - fork
          - popen
          - source

    - name: rate-limit-tool-calls
      action: flag
      maxCallsPerMinute: 120

    - name: token-budget
      action: flag
      maxTokens: 50000

Hot-reload: Edit the YAML file — the policy engine swaps atomically without restarting the proxy.

RBAC example:

    - name: admin-only-tool
      action: block
      tools:
        deny: [dangerous_operation]
      rbac:
        scopes: [admin]
        clientIds: [^trusted-agent-]

MCP Server Integration

MCP Guardian runs as a first-class MCP server, exposing security tools to AI assistants:

{
  "mcpServers": {
    "guardian": {
      "command": "npx",
      "args": ["@mcp-guardian/server"]
    }
  }
}

Available tools:

• scan_security — CVE, auth, typo-squat, and secret scanning

• audit_costs — Token usage and cost estimation

• check_health — Latency, success rate, and tool count

• full_report — Complete security-cost-health report (JSON/markdown/text)

Available resources:

• mcp-guardian://latest-scan — Most recent security scan results

Available prompts:

• audit-config — Generates audit instructions for an MCP config

Security Model

Production Deployment

Kubernetes (Helm)

helm repo add mcp-guardian https://rudraneel93.github.io/mcp-guardian
helm install guardian mcp-guardian/mcp-guardian \
  --set persistence.enabled=true \
  --set metrics.enabled=true \
  --set secrets.mode=external \
  --set secrets.existingSecret=mcp-guardian-secrets

The Helm chart includes:

• Liveness/readiness probes (/healthz, /readyz on port 9090)

• Resource limits (CPU 100m–500m, memory 256Mi–512Mi)

• Security context (non-root, read-only root filesystem, all capabilities dropped)

• NetworkPolicy (intra-namespace proxy traffic, CIDR-restricted dashboard)

• ExternalSecrets support (Vault, SOPS)

Docker

docker run -v $(pwd)/mcp.json:/etc/mcp-guardian/config.json \
  -v $(pwd)/policy.yaml:/etc/mcp-guardian/policy.yaml \
  ghcr.io/rudraneel93/mcp-guardian:latest \
  proxy --config /etc/mcp-guardian/config.json --policy /etc/mcp-guardian/policy.yaml

Environment Variables

Architecture

                    ┌──────────────────────────┐
                    │    MCP Guardian Proxy     │
                    │  ┌────────────────────┐  │
 AI Client ──JSON-RPC→│  Policy Engine       │──→ Upstream MCP Server
                    │  │  (audit/warn/block) │  │         │
                    │  └────────┬───────────┘  │         │
                    │           │              │         │
                    │  ┌────────▼───────────┐  │         │
                    │  │  HistoryDatabase    │  │         │
                    │  │  (better-sqlite3    │  │         │
                    │  │   WAL + lockfile)   │  │         │
                    │  └────────────────────┘  │         │
                    └──────────────────────────┘         │
                                                        │
              ┌─────────────────────────────────────────┘
              │
    ┌─────────▼──────────┐    ┌──────────────┐    ┌──────────┐
    │  Security Scanner   │    │  Cost Auditor │    │  Health  │
    │  • CVE (OSV+NVD)   │    │  • tiktoken   │    │  Monitor │
    │  • Auth probing     │    │  • litellm    │    │  • JSON- │
    │  • Typo-squat       │    │  • per-model  │    │    RPC   │
    │  • Secret (50+      │    │    pricing    │    │    probe │
    │    + entropy)       │    │               │    │  • latency│
    │  • Command AST      │    └──────────────┘    └──────────┘
    │  • Response inspect │
    └────────────────────┘

Data Flow

1. AI client sends tools/call JSON-RPC to proxy

2. Proxy extracts JWT identity → validates (algorithm-pinned, audience/issuer-checked)

3. Policy engine evaluates context (tool name, arguments, RBAC) → block/flag/pass

4. If passed, forwards to upstream MCP server; if blocked, returns JSON-RPC error

5. Records call metadata (tokens, duration, agent ID) to SQLite

6. Circuit breaker monitors upstream health; health probes run periodically

7. Dashboard receives real-time events via WebSocket; Prometheus scrapes /metrics

Development

# Clone and install
git clone https://github.com/rudraneel93/mcp-guardian.git
cd mcp-guardian
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Type-check
pnpm typecheck

# Run specific test suites
cd packages/core && npx vitest run
cd packages/server && npx vitest run
cd packages/cli && npx vitest run

# Run corpus evaluation
pnpm eval

# Development mode (hot-reload)
pnpm dev

FAQ

How is MCP Guardian different from a WAF or API gateway?

A WAF inspects HTTP traffic patterns; MCP Guardian operates at the MCP protocol layer — it understands tools/call semantics, tool names, argument schemas, and agent identities. It can block execute_command calls while allowing read_file, enforce per-tool rate limits, and validate JWT claims with algorithm pinning. It also scans MCP servers for CVEs, secrets, and typo-squatting — things a WAF cannot do.

Does the proxy add latency?

Typically 5–25ms for policy evaluation (regex + schema + semantic shell analysis). JWT validation adds another 5–15ms. The total proxy overhead is under 50ms for most calls. If LLM semantic analysis is enabled, that adds 200–800ms per tool definition scan (not per call — it runs once during manifest verification, not on every intercepted request).

Can I run it without blocking anything?

Yes. Set the policy mode to audit:

policy:
  mode: audit

This logs every decision without blocking or flagging. Use it to understand what your agents are calling before enforcing rules. You can also run mcp-guardian proxy --policy ./policy.yaml --dry-run to simulate blocking against historical call records.

What happens if the policy engine crashes?

The proxy does not pass traffic through if the engine is unavailable — it returns a JSON-RPC error to the client. This is intentional fail-safe behavior. The policy engine is a synchronous, in-process evaluator (no network calls for regex/schema rules), so crashes are extremely unlikely. The LLM semantic layer gracefully degrades to an info-level "skipped" result if the API is unreachable.

Can I use it with multiple replicas?

Yes, with caveats. The proxy works single-instance or multi-replica, but rate limiting and session state require Redis (REDIS_URL) in multi-replica mode. Without Redis, rate limits are per-pod and session tokens from pod A are invalid on pod B. Set GUARDIAN_STRICT_MODE=true to refuse startup if Redis is missing in a multi-replica/K8s environment. For the audit database, use separate DB paths (MCP_GUARDIAN_DB_PATH) per instance, or migrate to PostgreSQL (planned for v2.4).

Does the LLM semantic layer send my data to Anthropic?

Only if you configure ANTHROPIC_API_KEY. The semantic scanner sends tool definitions (name + description + inputSchema) to Claude for security analysis — never the actual tool call arguments or response content. Tool definitions are metadata, not user data. You can disable the semantic layer entirely with --skip-semantic or by not setting the API key.

How do I add my own secret patterns?

Add them to the MCP_GUARDIAN_SECRET_ALLOWLIST environment variable (comma-separated) to suppress false positives. For custom detection patterns, you can extend src/scanners/secret-scanner.ts and rebuild. The entropy threshold (4.5 bits per character) is also configurable in source.

Can I use it as a library in my own tool?

Yes. The @mcp-guardian/core package exports the detection engine directly:

import { scanServer, fetchToolsFromStdio } from '@mcp-guardian/core';

const tools = await fetchToolsFromStdio({ command: 'npx', args: ['@my-mcp-server'] });
const result = await scanServer('my-server', tools, 'stdio');
// result.status: 'clean' | 'warning' | 'critical'
// result.tools: per-tool scan results with issues

The root package (@mcp-guardian/server) exports the full CLI, proxy, and MCP server.

What's the default policy if I don't provide one?

The default-policy.yaml shipped with the package blocks shell injection patterns (curl, wget, rm -rf, command chaining, /etc/passwd), explicitly denies dangerous tools (execute_command, bash, sh, eval, exec, etc.), rate-limits at 120 calls/min, flags tokens over 50K, and applies default_action: block — meaning anything not explicitly allowed is blocked. You can override this with your own policy file.

Does it work with Windows?

The TypeScript codebase is platform-agnostic, but the stdio proxy spawns child processes and uses Unix signal handling. Windows support via WSL2 is fully functional. Native Windows cmd.exe / PowerShell is experimentally supported but not the primary target. The HTTP/SSE proxy transport works on any platform.

How do I get alerted when something gets blocked?

Set ALERT_WEBHOOK_URL to a Slack or Discord webhook URL, and optionally ALERT_MIN_SEVERITY (default: warning). The alerter fires on policy blocks, circuit breaker state changes, and cost threshold breaches. Messages include server name, rule triggered, and timestamp.

Where is the database stored?

~/.mcp-guardian/history.db by default. Override with MCP_GUARDIAN_DB_PATH. The database uses SQLite with WAL mode, advisory file locking, and automatic purging of records older than 30 days. For tests, pass ':memory:' to use an in-memory database.

How do I verify my policy before deploying?

Use dry-run mode:

mcp-guardian proxy --policy ./new-policy.yaml --dry-run

This evaluates the policy against every call record in your history database and prints a per-server block/pass breakdown without activating the proxy. If the block rate is unexpectedly high or low, adjust rules before deploying.

How do AI clients authenticate with OAuth?

The proxy validates JWT bearer tokens in the Authorization header of tools/call requests. However, AI clients like Cline and Claude Desktop don't natively generate OAuth tokens. You have three options:

1. Token injection via MCP config — Set env.AUTH_TOKEN in your MCP server config. The proxy passes it as a Bearer token to upstream servers and validates it if --auth-required is set.

2. API gateway pattern — Place an OAuth proxy (e.g., oauth2-proxy, Pomerium) in front of MCP Guardian. The gateway issues tokens; MCP Guardian validates them.

3. Service account tokens — Generate a long-lived service account JWT and configure it as AUTH_TOKEN. Rotate it manually or via vault.

RBAC scopes are defined in your policy YAML under rules[].rbac.scopes and mapped to JWT claims (the scope or scopes claim in the token). DPoP (RFC 9449) requires the client to sign a proof-of-possession JWT per request — this is functional in code but not yet supported by any mainstream AI client.

How accurate is token counting?

For OpenAI models (GPT-4o, o1, o3), counting uses tiktoken with o200k_base encoding — these are exact (±1%). For other providers:

Results are flagged with isEstimate: true when char-ratio counting is used. Treat non-OpenAI cost figures as estimates, not accounting-grade numbers.

How does CVE scoring work? Why aren't 100 CVEs penalized more?

MCP Guardian uses logarithmic compound scoring: each additional CVE in the same severity tier adds diminishing penalty. 1 critical CVE = −30, 2 = −60, 5 = −100, 10 = −130, 100 = −230. This prevents a single vulnerable package from zeroing the entire score while still scaling penalty with volume. CVE recency and EPSS (Exploit Prediction Scoring System) integration is planned for v2.4.

How do I set up mTLS?

mTLS requires:

1. A Certificate Authority (CA) — you can use your existing PKI or create one with openssl

2. A client certificate for each upstream MCP server signed by that CA

3. The CA certificate configured in MCP Guardian via environment variables

Set MCP_TLS_CA_PATH=/path/to/ca.pem and MCP_TLS_CLIENT_CERT_PATH=/path/to/client.crt, MCP_TLS_CLIENT_KEY_PATH=/path/to/client.key per server in your MCP config's env section. A mcp-guardian certs init helper command is planned for v2.4 to automate this.

What happens if my policy YAML is malformed?

The proxy fails closed — malformed YAML causes a startup error and the proxy refuses to start. It does not silently fall back to the last good policy or default to audit mode. Use --dry-run to validate new policies before deploying:

mcp-guardian proxy --policy ./new-policy.yaml --dry-run

How do I contribute?

See CONTRIBUTING.md for guidelines. The monorepo uses pnpm workspaces with turbo for build orchestration. Run pnpm install && pnpm build && pnpm test to verify your setup. All PRs must pass the 80% coverage threshold and the red-team corpus evaluation (F1 ≥ 85%).

Is it production-ready?

MCP Guardian is production-grade for controlled environments (single-instance or Redis-backed multi-replica with GUARDIAN_STRICT_MODE). The database layer uses better-sqlite3 with WAL mode and advisory file locking — crash-safe and non-blocking. It handles the core use case — active policy enforcement with audit trails — reliably. For high-trust enterprise deployments, a third-party security audit is planned for v2.5. See SECURITY.md for details on our security posture.

Roadmap

v2.4

• PostgreSQL migration option for multi-replica deployments

• OPA/Rego policy integration

• Multi-user proxy (separate DB schemas per team)

v2.5

• Third-party security audit (OAuth/JWT/RBAC/DPoP)

• Adversarial fuzzing CI pipeline

• Hosted SaaS pilot

v3.0

• Plugin architecture for custom scanners

• gRPC transport support

• Real-time cost dashboards with budget alerts

License

MIT — see LICENSE.

Built with TypeScript, better-sqlite3, pino, prom-client, jose, shell-quote, tiktoken, commander, chalk, and lru-cache.