MCPShield

AI Agent Security Platform - Discover and secure MCP servers across your organization.

What is MCPShield?

MCPShield is a security platform that automatically discovers, monitors, and assesses the risk of MCP (Model Context Protocol) servers running on your machines. As AI agents (Claude, Cursor, Windsurf) increasingly use MCP servers to interact with filesystems, databases, and APIs, MCPShield helps you maintain visibility and control.

Features

• Automatic Discovery - Agent scans for MCP configurations on Windows, macOS, and Linux
• Risk Assessment - Each server is scored based on capabilities, environment variables, and scope
• Centralized Dashboard - View all MCP servers across your organization in one place
• Multi-Tenancy - Secure isolation between organizations
• Real-time Status - Track which servers are active or dormant

Prerequisites

• Python 3.11+
• Node.js 18+
• PostgreSQL 15+ (or SQLite for development)
• Docker and Docker Compose (for containerized deployment)

Environment Setup

Before starting MCPShield, you must generate and set a JWT secret key:

Bash / macOS / Linux:

export JWT_SECRET=$(python3 -c "import secrets; print(secrets.token_hex(32))")

PowerShell (Windows):

$env:JWT_SECRET = python -c "import secrets; print(secrets.token_hex(32))"

Important: The backend will refuse to start without JWT_SECRET set. For persistent configuration, add it to backend/.env or your system environment variables.

Quick Start

Option 1: Docker Compose (Recommended)

# 1. Generate and set JWT secret
export JWT_SECRET=$(python3 -c "import secrets; print(secrets.token_hex(32))")

# 2. Start all services
docker-compose up -d

# 3. Access the dashboard
# Frontend: http://localhost:3000
# Backend API: http://localhost:8000
# API Docs: http://localhost:8000/docs

PowerShell:

$env:JWT_SECRET = python -c "import secrets; print(secrets.token_hex(32))"
docker-compose up -d

Option 2: Manual Setup

1. Start the Backend

cd backend
python -m venv venv
.\venv\Scripts\activate  # Windows
source venv/bin/activate  # macOS/Linux
pip install -r requirements.txt
uvicorn app.main:app --reload

2. Start the Frontend

cd frontend
npm install
npm run dev

3. Install the Agent

cd agent
pip install -e .

4. Configure and Scan

# Open http://localhost:3000, register, create an agent, copy the API key

mcpshield configure --api-key mcp_sk_YOUR_KEY --api-url http://localhost:8000
mcpshield scan

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Agent     │────▶│   Backend   │◀────│  Frontend   │
│  (Python)   │     │  (FastAPI)  │     │  (Next.js)  │
└─────────────┘     └──────┬──────┘     └─────────────┘
                           │
                    ┌──────▼──────┐
                    │  Database   │
                    │(PostgreSQL) │
                    └─────────────┘

Project Structure

mcpshield/
├── backend/          # FastAPI backend API
├── agent/            # Python CLI agent
├── frontend/         # Next.js dashboard
└── DOCUMENTATION.md  # Full documentation

Tech Stack

Component	Technology
Backend	FastAPI, SQLAlchemy, PostgreSQL
Frontend	Next.js 14, React, TailwindCSS
Agent	Python, Click CLI
Auth	JWT tokens, API keys

Documentation

See DOCUMENTATION.md for complete documentation including:

• Full API reference
• Database schema
• Risk scoring algorithm
• Deployment guide

Development

Running Tests

# Backend
cd backend && pytest

# Frontend
cd frontend && npm run build

License

MIT License - see LICENSE

Status

MVP Complete - All core features implemented and tested:

• ✅ Backend API with auth
• ✅ Python agent with scanning
• ✅ React dashboard
• ✅ Risk scoring
• ✅ Multi-tenancy