mcp-shield 🛡️

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

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:

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

API Reference

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