# MCPShield

> AI agent security platform that discovers, monitors, and assesses the risk of MCP servers across your organization. Automatic scanning on Windows, macOS, and Linux with risk scoring and a centralized multi-tenant dashboard.

- **Type:** MCP server
- **Install:** `agentstack add mcp-runtimeadmin-mcpshield`
- **Verified:** Pending review
- **Seller:** [RunTimeAdmin](https://agentstack.voostack.com/s/runtimeadmin)
- **Installs:** 0
- **Category:** [Data & Analytics](https://agentstack.voostack.com/c/data-and-analytics)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [RunTimeAdmin](https://github.com/RunTimeAdmin)
- **Source:** https://github.com/RunTimeAdmin/MCPShield
- **Website:** https://mcpshield.app/

## Install

```sh
agentstack add mcp-runtimeadmin-mcpshield
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MCPShield

**Security platform for MCP servers and AI agents**

*Free tier at [mcpshield.app](https://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](https://mcpshield.app)  ·  [Documentation](DOCUMENTATION.md)  ·  [PyPI](https://pypi.org/project/mcpshield-agent/)  ·  [Issues](https://github.com/RunTimeAdmin/MCPShield/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

```mermaid
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](https://app.mcpshield.app/register), then install the agent:

```bash
# 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:**

```bash
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:

```mermaid
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

```mermaid
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

```mermaid
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**
```bash
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**
```bash
cd frontend
npm install
npm run dev                       # http://localhost:3000
```

**Agent (from source)**
```bash
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.

```bash
# 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](https://github.com/RunTimeAdmin)
- **Source:** [RunTimeAdmin/MCPShield](https://github.com/RunTimeAdmin/MCPShield)
- **License:** MIT
- **Homepage:** https://mcpshield.app/

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-runtimeadmin-mcpshield
- Seller: https://agentstack.voostack.com/s/runtimeadmin
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.