mcp-shield 🛡️

The security runtime for MCP servers. Every tool call inspected. Every attack blocked. Every decision logged.

Python PyPI Tests Status

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI assistants (Claude, Cursor, Copilot) connect to external tools and services — file systems, APIs, databases, browsers — through MCP servers.

Think of MCP servers as plugins that give AI agents real-world capabilities.

The Problem

MCP servers run as trusted processes on your machine with broad access:

Access	Risk
🗂️ Filesystem	Read `/etc/passwd`, steal SSH keys
🌐 Network	SSRF to `169.254.169.254` (AWS metadata endpoint)
🔑 Environment variables	Steal API keys, tokens, secrets
⚙️ Shell	Execute arbitrary commands

A malicious or compromised MCP server can silently exfiltrate your secrets, pivot to internal infrastructure, or execute code — and you'd never know.

This is not theoretical. A real SSRF vulnerability was found in an MCP OAuth HTTP transport implementation that allowed exactly this class of attack.

How mcp-shield Fixes This

mcp-shield sits between your AI agent and the MCP server as a policy enforcement layer. Before any tool executes, mcp-shield evaluates it. If it's not explicitly allowed — it's blocked.

AI Agent
   │
   ▼
mcp-shield /inspect
   │
   ├── Tool allowlist check      →  "read_secrets" not in allowlist  → 🚫 BLOCK
   ├── Blocked pattern check     →  "ssrf_fetch" is dangerous        → 🚫 BLOCK
   ├── Argument scanning         →  "169.254.169.254" in args        → 🚫 BLOCK
   │   (recursive, nested dicts)
   └── Passed all checks         →  ✅ ALLOW → MCP Server executes
                                          │
                                          ▼
                                     Audit Log (SQLite)
                              timestamp | server | tool | decision | reason

Install

pip install mcpshield-runtime

Or clone and run locally:

git clone https://github.com/srisowmya2000/mcp-shield
cd mcp-shield
python3 -m venv .venv && source .venv/bin/activate
pip install fastapi uvicorn pydantic pydantic-settings mcp httpx pyyaml rich
uvicorn runtime.api.main:app --reload

Open:

API docs → http://localhost:8000/docs
Live dashboard → http://localhost:8000/dashboard

Live Demo

# Start mcp-shield
uvicorn runtime.api.main:app --reload

# 🚫 Attempt secret theft → BLOCKED
curl -X POST http://localhost:8000/inspect \
  -H "Content-Type: application/json" \
  -d '{"server_name":"evil","policy":"default","tool_call":{"tool_name":"read_secrets","arguments":{}}}'
# → {"decision":"BLOCK","reason":"Tool 'read_secrets' is not in the allowed_tools list","blocked":true}

# 🚫 Attempt SSRF to AWS metadata endpoint → BLOCKED
curl -X POST http://localhost:8000/inspect \
  -H "Content-Type: application/json" \
  -d '{"server_name":"evil","policy":"default","tool_call":{"tool_name":"ssrf_fetch","arguments":{"url":"http://169.254.169.254/latest/meta-data/"}}}'
# → {"decision":"BLOCK","reason":"Argument contains blocked pattern: '169.254.169.254'","blocked":true}

# ✅ Safe tool → ALLOWED
curl -X POST http://localhost:8000/inspect \
  -H "Content-Type: application/json" \
  -d '{"server_name":"safe","policy":"default","tool_call":{"tool_name":"safe_tool","arguments":{"name":"Sri"}}}'
# → {"decision":"ALLOW","reason":"Passed all policy checks","blocked":false}

CLI

# Inspect a tool call
python3 -m runtime.cli inspect read_secrets
# → 🚫 BLOCKED — Tool 'read_secrets' is not in the allowed_tools list

python3 -m runtime.cli inspect safe_tool
# → ✅ ALLOWED — Passed all policy checks

# Score a server's risk level
python3 -m runtime.cli risk "read_secrets,ssrf_fetch,safe_tool"
# → 🔴 HIGH RISK (score: 80)
# → High-risk tools: ['read_secrets', 'ssrf_fetch']
# → Do not run without strict policy. Use isolated network.

# View live audit log
python3 -m runtime.cli audit

# View stats
python3 -m runtime.cli stats
# → Total: 6 | ✅ Allowed: 2 | 🚫 Blocked: 4 (67% block rate)

Policies

Drop a YAML file in policies/ and reference it by name in any /inspect call.

# policies/default.yaml
allowed_tools:
  - safe_tool
  - list_files
  - get_time

block_network: true
block_env_access: true

blocked_arg_patterns:
  - "169.254.169.254"   # AWS metadata SSRF
  - "169.254.170.2"     # ECS metadata SSRF
  - "localhost"
  - "127.0.0.1"
  - "/etc/passwd"
  - "/etc/shadow"
  - "file://"
  - "gopher://"

max_memory_mb: 256
execution_timeout_seconds: 30

Switch policy per server:

POST /inspect  →  { "policy": "strict", ... }

Two policies included: default and strict (zero-trust).

Features

Feature	Description
🔒 Policy Engine	YAML allowlists + blocked patterns, per-server policies
🔍 Argument Scanning	Recursively scans nested args for SSRF, path traversal, dangerous patterns
📋 Audit Logger	Every decision logged to SQLite — timestamp, server, tool, reason
🐳 Docker Sandbox	Hardened containers: `--cap-drop=ALL`, `--network=none`, `--read-only`
🔥 Firecracker Backend	microVM isolation — each server gets its own Linux kernel (Linux/KVM only)
📊 Risk Scorer	Scores MCP servers LOW / MEDIUM / HIGH based on tool capabilities
🖥️ Live Dashboard	Real-time web UI at `/dashboard` — live block/allow feed, flash animations
⚡ CLI	`mcpshield inspect`, `audit`, `stats`, `risk` with rich colored output

API Reference

Endpoint	Method	Description
`/health`	GET	Service health check
`/inspect`	POST	Evaluate tool call → ALLOW / BLOCK
`/audit`	GET	Recent audit log entries
`/audit/stats`	GET	Total / allowed / blocked counts
`/risk/score`	POST	Score server risk by tool list
`/sandbox/launch`	POST	Launch MCP server in hardened Docker container
`/sandbox/stop/{name}`	POST	Stop a running sandbox
`/sandbox/list`	GET	List running sandboxes
`/dashboard`	GET	Live real-time decision dashboard
`/docs`	GET	Interactive Swagger API docs

Docker Sandbox

Every MCP server launched via mcp-shield runs with:

--cap-drop=ALL          no Linux capabilities
--no-new-privileges     no privilege escalation
--read-only             immutable filesystem
--network=none          no network access
--memory=256m           memory limit
--cpus=0.5              CPU limit
--pids-limit=64         process limit
--tmpfs=/tmp            ephemeral tmp only

Firecracker microVM Backend

For stronger isolation, mcp-shield supports Firecracker microVMs — each MCP server gets its own Linux kernel. A kernel exploit inside the VM cannot reach the host.

Docker:       shared kernel → kernel exploit = host at risk
Firecracker:  own kernel    → kernel exploit = contained in VM

Requires Linux with KVM. See docs/firecracker-setup.md.

Architecture

mcp-shield/
├── runtime/
│   ├── api/
│   │   └── main.py              # FastAPI — all endpoints
│   ├── policy_engine.py         # YAML policy loader + evaluator
│   ├── audit_logger.py          # SQLite decision log
│   ├── risk_scorer.py           # LOW/MEDIUM/HIGH risk scoring
│   ├── cli.py                   # Typer CLI
│   ├── models.py                # Pydantic schemas
│   └── sandbox/
│       ├── base.py              # Abstract backend interface
│       ├── docker_backend.py    # Hardened Docker sandbox
│       └── firecracker_backend.py  # microVM backend (Linux/KVM)
├── policies/
│   ├── default.yaml
│   └── strict.yaml
├── examples/
│   ├── malicious_mcp_server/    # Demo attacker (SSRF + secret theft + exec)
│   └── safe_mcp_server/         # Demo benign server
├── docs/
│   ├── threat-model.md          # Attack scenarios + limitations
│   └── firecracker-setup.md     # Firecracker setup guide
└── tests/                       # 12 tests — all passing

Tests

pip install pytest
pytest tests/ -v
# 12 passed in 0.11s

Covers: tool allowlist blocking, SSRF argument detection, nested arg scanning, strict policy enforcement, edge cases, unknown policy handling.

Threat Model

See docs/threat-model.md for:

Attack scenarios (SSRF, secret theft, command execution, path traversal)
What mcp-shield blocks vs what it doesn't
Defense in depth recommendations

Roadmap

Policy engine (allowlist + pattern scanning)
Audit logger (SQLite)
FastAPI REST surface
Docker sandbox backend (hardened)
Demo malicious MCP server
Risk scorer (LOW / MEDIUM / HIGH)
CLI (mcpshield inspect, audit, stats, risk)
Real-time dashboard
Firecracker microVM backend
PyPI package (pip install mcpshield-runtime)
Threat model documentation
Prompt injection detection
Per-tool argument schema validation
Webhook alerts on BLOCK events

License

MIT — see LICENSE

Author

Sri Sowmya Nemani — Security researcher & engineer. Bug bounty | MCP security | AI agent security

GitHub · PyPI

mcp_Shield