MCPShield

MCPShield

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.

[](https://pypi.org/project/mcpshield-agent/) [](https://pypi.org/project/mcpshield-agent/) [](LICENSE) []()

Website  ·  [Documentation](DOCUMENTATION.md)  ·  PyPI  ·  Issues

---

The Problem

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.

---

How It Works

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

---

Get Running in 5 Minutes

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.app

The 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

---

Features

| 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 | | Deep Scan | mcpshield scan --deep connects to each active MCP server and flags tool-description poisoning — hidden prompt-injection instructions in tool metadata | | 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 |

---

Risk Scoring Model

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+35"]
    scanner --> docker["Docker / container access+20"]
    scanner --> path["Sensitive path access+20"]
    scanner --> tools["High-risk tool names+25"]
    scanner --> db["Database access+15"]
    scanner --> fs["Filesystem write tools+15"]
    scanner --> env["Sensitive env var names+15"]
    scanner --> net["Network / HTTP tools+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.

---

Architecture

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

Data model

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
    }

---

Tech Stack

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

---

Project Structure

mcpshield/
├── agent/
│   └── mcpshield_agent/
│       ├── cli.py            # scan / configure / status / daemon commands
│       ├── scanner.py        # MCP config discovery (Claude, Cursor, Windsurf)
│       ├── tool_scanner.py   # --deep: tool-description poisoning detection
│       ├── client.py         # API client (heartbeat + report)
│       └── config.py         # API key storage (0600 perms)
├── backend/
│   └── app/
│       ├── routers/          # auth · agents · mcp · alerts · dashboard · billing
│       ├── utils/risk_scorer.py  # compiled-regex weighted scoring engine
│       ├── 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)

---

Manual Setup

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 8000

Frontend

cd frontend
npm install
npm run dev                       # http://localhost:3000

Agent (from source)

cd agent
pip install -e .
mcpshield configure --api-key YOUR_KEY --api-url http://localhost:8000
mcpshield scan

---

API Authentication

| Client | Method | |---|---| | Web users | Authorization: Bearer — 30-min access token, 7-day refresh | | Agents | X-API-Key: — issued per agent, stored SHA-256 hashed |

Full API reference: [DOCUMENTATION.md](DOCUMENTATION.md) or /docs on any running instance.

---

Contributing

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 build

---

License

MIT — see [LICENSE](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: RunTimeAdmin
• Source: RunTimeAdmin/MCPShield
• License: MIT
• Homepage: https://mcpshield.app/

Install and usage instructions live in the source repository linked above.