Security platform for MCP servers and AI agents
Free tier at mcpshield.app · Agent is MIT licensed · Self-host from source
Discover shadow AI infrastructure. Score every risk. Stop blind spots before attackers find them.
Website · Documentation · PyPI · Issues
Developers are silently connecting AI tools — Claude, Cursor, Windsurf, ChatGPT — to production databases, file systems, shells, and internal APIs via MCP (Model Context Protocol) servers. Security teams have zero visibility into this shadow AI infrastructure.
A single misconfigured MCP server can give an AI assistant full read/write access to your database, file system, or secrets store — with no audit trail, no approval, and no alerting.
MCPShield finds every MCP server across your organization, scores its risk, and puts security teams back in control.
flowchart LR
subgraph dev["Developer Endpoints"]
direction TB
W[Windows]
M[macOS]
L[Linux]
end
subgraph agent["mcpshield-agent"]
direction TB
S1[Discover MCP configs]
S2[Score risk 0–100]
S3[Report via API key]
S1 --> S2 --> S3
end
subgraph backend["MCPShield Backend • FastAPI"]
direction TB
B1[Risk engine]
B2[Alert generator]
B3[(PostgreSQL)]
B1 --> B2 --> B3
end
subgraph ui["Security Dashboard • Next.js"]
direction TB
U1[Risk overview]
U2[Alerts]
U3[Agent status]
end
dev -->|"curl install + scan"| agent
agent -->|X-API-Key| backend
backend -->|JWT| ui
Option A — Hosted (recommended): Sign up free at mcpshield.app, then install the agent:
# One-liner installer (macOS / Linux)
curl -fsSL https://install.mcpshield.app | sh
# Windows
pip install mcpshield-agent
mcpshield configure --api-key YOUR_KEY --api-url https://api.mcpshield.appThe installer prompts for your API key (from Settings → Agents) and starts the background service automatically.
Option B — Self-host with Docker:
git clone https://github.com/RunTimeAdmin/MCPShield.git && cd MCPShield
cp .env.production.example .env # fill in JWT_SECRET, DB creds, etc.
docker compose -f docker-compose.prod.yml up -d
# Frontend → https://your-domain
# API → https://your-domain/api
# API docs → https://your-domain/api/docs| Capability | Description |
|---|---|
| Automatic Discovery | Scans Claude Desktop, Cursor, Windsurf, and custom MCP config paths on Windows, macOS, and Linux |
| Risk Scoring Engine | Weighted 0–100 score across shell access, filesystem writes, credential exposure, network calls, and tool surface area |
| Real-time Alerts | Fires on new high-risk servers and on score increases > 10 points |
| Centralized Dashboard | Org-wide risk distribution, top-risk servers, per-agent heartbeat, and alert history |
| Multi-tenant | Full data isolation between organizations — users, agents, servers, and alerts never cross org boundaries |
| Dual Auth | JWT bearer tokens for the web UI; SHA-256-hashed API keys for agent reporting |
| Smart Scanning | Agent skips re-scans when config mtimes are unchanged — minimal CPU overhead |
| CISA KEV Enrichment | Flags MCP servers exposing tools tied to known actively-exploited CVEs (CISA Known Exploited Vulnerabilities catalog) |
| Privacy-first | Environment variable names only — credential values are never captured or transmitted |
MCPShield analyzes each MCP server's configuration and calculates a risk score from 0–100:
flowchart TD
cfg["MCP config file"] --> scanner["Risk Scoring Engine"]
scanner --> sh["Shell / exec tools<br/>+35"]
scanner --> docker["Docker / container access<br/>+20"]
scanner --> path["Sensitive path access<br/>+20"]
scanner --> tools["High-risk tool names<br/>+25"]
scanner --> db["Database access<br/>+15"]
scanner --> fs["Filesystem write tools<br/>+15"]
scanner --> env["Sensitive env var names<br/>+15"]
scanner --> net["Network / HTTP tools<br/>+10"]
sh & docker & path & tools & db & fs & env & net --> score["Final Score (capped 100)"]
score --> crit["🔴 Critical 85–100"]
score --> high["🟠 High 60–84"]
score --> med["🟡 Medium 30–59"]
score --> low["🟢 Low 0–29"]
Alerts are generated automatically for any server scoring ≥ 60, and for existing servers whose score jumps by more than 10 points between scans.
graph TD
subgraph agents["Agents (mcpshield-agent)"]
A1["Windows endpoint"]
A2["macOS endpoint"]
A3["Linux endpoint"]
end
subgraph api["Backend (FastAPI + PostgreSQL)"]
R1["/agents/report — receive scan results"]
R2["/mcp/servers — query servers + risk"]
R3["/alerts — alert CRUD"]
R4["/auth — org + user management"]
DB[(PostgreSQL)]
R1 & R2 & R3 & R4 --> DB
end
subgraph frontend["Dashboard (Next.js 14 App Router)"]
P1["Overview"]
P2["Servers table"]
P3["Alerts"]
P4["Settings"]
end
agents -->|"X-API-Key (hashed at rest)"| api
frontend -->|"Bearer JWT (30 min access / 7 day refresh)"| api
erDiagram
Organization ||--o{ User : has
Organization ||--o{ Agent : registers
Agent ||--o{ MCPServer : reports
MCPServer ||--o{ Alert : triggers
Organization {
uuid id
string name
string alert_email
string subscription_tier
}
Agent {
uuid id
string hostname
string api_key_hash
datetime last_seen
}
MCPServer {
uuid id
string name
int risk_score
string risk_level
json config_snapshot
}
Alert {
uuid id
string severity
string message
bool resolved
}
| Layer | Technology |
|---|---|
| Backend | FastAPI, SQLAlchemy 2.0, Alembic, PostgreSQL / SQLite |
| Frontend | Next.js 14 App Router, React 18, Tailwind CSS, Recharts |
| Agent | Python 3.11+, Click, psutil |
| Auth | HS256 JWT, bcrypt passwords, SHA-256 API key hashing |
| Rate limiting | slowapi — 5/min register, 10/min login, 10/min agent report |
| Deployment | Docker + Docker Compose, Caddy (automatic TLS) |
mcpshield/
├── agent/
│ └── mcpshield_agent/
│ ├── scanner.py # MCP config discovery + mtime caching
│ ├── service.py # daemon loop with smart scan skipping
│ └── risk_scorer.py # compiled-regex weighted scoring engine
├── backend/
│ └── app/
│ ├── routers/ # auth · agents · mcp · alerts · dashboard
│ ├── models.py # SQLAlchemy ORM: Org → Users → Agents → Servers → Alerts
│ └── schemas.py # Pydantic v2 request/response contracts
├── frontend/
│ ├── app/dashboard/ # Next.js App Router pages
│ └── lib/
│ ├── api.ts # typed APIClient with TTL caching
│ └── auth-context.tsx # org + user session management
├── docker-compose.yml # dev (source bind-mounts, sqlite ok)
└── docker-compose.prod.yml # production (GHCR images, Caddy TLS, Postgres)
Expand for step-by-step instructions
Requirements: Python 3.11+, Node.js 18+, PostgreSQL 15+ (or SQLite for dev)
Backend
cd backend
python -m venv venv
source venv/bin/activate # macOS/Linux
.\venv\Scripts\activate # Windows
pip install -r requirements.txt
export JWT_SECRET=$(python3 -c "import secrets; print(secrets.token_hex(32))")
uvicorn app.main:app --reload --port 8000Frontend
cd frontend
npm install
npm run dev # http://localhost:3000Agent (from source)
cd agent
pip install -e .
mcpshield configure --api-key YOUR_KEY --api-url http://localhost:8000
mcpshield scan| Client | Method |
|---|---|
| Web users | Authorization: Bearer <token> — 30-min access token, 7-day refresh |
| Agents | X-API-Key: <key> — issued per agent, stored SHA-256 hashed |
Full API reference: DOCUMENTATION.md or /docs on any running instance.
Issues and PRs are welcome. For significant changes, open an issue first to discuss the approach.
# Backend tests
cd backend && pytest
# Frontend type check
cd frontend && npm run buildMIT — see LICENSE