Skip to content

DOCUMENTATION.md

Latest commit

 

History

History
1074 lines (861 loc) · 29.8 KB

DOCUMENTATION.md

File metadata and controls

1074 lines (861 loc) · 29.8 KB
Raw

MCPShield - Complete Project Documentation

Version: 0.1.2
Last Updated: June 2026

Table of Contents

  1. Project Overview
  2. Architecture
  3. Technology Stack
  4. Backend API
  5. Python Agent
  6. Frontend Dashboard
  7. Database Schema
  8. Authentication & Security
  9. Risk Scoring System
  10. Local Development Setup
  11. Testing
  12. Project Structure
  13. API Reference
  14. Current Status
  15. Next Steps

Project Overview

What is MCPShield?

MCPShield is an AI Agent Security Platform that discovers, monitors, and assesses the security risk of MCP (Model Context Protocol) servers running across an organization's infrastructure.

Problem Statement

AI agents (Claude, Cursor, Windsurf, etc.) use MCP servers to interact with external systems like filesystems, databases, and APIs. These servers often run with elevated privileges and can pose significant security risks if not properly monitored.

Solution

MCPShield provides:

  • Automatic Discovery: Agent scans machines for MCP server configurations
  • Risk Assessment: Each server is scored based on its capabilities and configuration
  • Centralized Dashboard: Visualize all MCP servers across your organization
  • Multi-Tenancy: Isolate data between different organizations
  • Alerting: Get notified when high-risk servers are detected

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         MCPShield Architecture                       │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐        │
│  │   Machine 1  │     │   Machine 2  │     │   Machine N  │        │
│  │              │     │              │     │              │        │
│  │ ┌──────────┐ │     │ ┌──────────┐ │     │ ┌──────────┐ │        │
│  │ │  Agent   │ │     │ │  Agent   │ │     │ │  Agent   │ │        │
│  │ └────┬─────┘ │     │ └────┬─────┘ │     │ └────┬─────┘ │        │
│  │      │       │     │      │       │     │      │       │        │
│  │ ┌────▼─────┐ │     │ ┌────▼─────┐ │     │ ┌────▼─────┐ │        │
│  │ │MCP Config│ │     │ │MCP Config│ │     │ │MCP Config│ │        │
│  │ └──────────┘ │     │ └──────────┘ │     │ └──────────┘ │        │
│  └──────────────┘     └──────────────┘     └──────────────┘        │
│           │                   │                   │                 │
│           └───────────────────┼───────────────────┘                 │
│                               │                                      │
│                               ▼                                      │
│                    ┌─────────────────────┐                          │
│                    │   MCPShield API     │                          │
│                    │   (FastAPI/Python)  │                          │
│                    │                     │                          │
│                    │  • Authentication   │                          │
│                    │  • Risk Scoring     │                          │
│                    │  • Multi-Tenancy    │                          │
│                    └──────────┬──────────┘                          │
│                               │                                      │
│                               ▼                                      │
│                    ┌─────────────────────┐                          │
│                    │     Database        │                          │
│                    │  (PostgreSQL/SQLite)│                          │
│                    └──────────┬──────────┘                          │
│                               │                                      │
│                               ▼                                      │
│                    ┌─────────────────────┐                          │
│                    │  Frontend Dashboard │                          │
│                    │    (Next.js/React)  │                          │
│                    └─────────────────────┘                          │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Data Flow

  1. Agent Installation: User installs MCPShield agent on their machine
  2. Configuration: Agent is configured with an API key from the dashboard
  3. Scanning: Agent scans for MCP config files (Claude, Cursor, etc.)
  4. Reporting: Agent sends discovered servers to the API
  5. Risk Assessment: API calculates risk scores for each server
  6. Visualization: Dashboard displays servers, risks, and alerts

Technology Stack

Backend

Component Technology Version
Framework FastAPI 0.109+
Language Python 3.11+
ORM SQLAlchemy 2.0+
Validation Pydantic 2.0+
Database PostgreSQL / SQLite 15+ / 3.x
Authentication JWT (python-jose) -
Password Hashing bcrypt -
Migrations Alembic -

Agent

Component Technology Version
Language Python 3.8+
CLI Framework Click 8.1+
HTTP Client Requests 2.31+
Process Monitoring psutil 5.9+

Frontend

Component Technology Version
Framework Next.js 14.1
Language TypeScript 5.3+
UI Library React 18.2
Styling TailwindCSS 3.4
Components Radix UI -
Icons Lucide React -
Charts Recharts 2.10

Backend API

Location

backend/

Key Files

File Purpose
app/main.py FastAPI application entry point
app/models.py SQLAlchemy ORM models
app/schemas.py Pydantic request/response schemas
app/auth.py JWT and API key authentication
app/database.py Database connection and session management
app/routers/auth.py User authentication endpoints
app/routers/agents.py Agent management endpoints
app/routers/mcp.py MCP server endpoints
app/routers/alerts.py Alert management endpoints
app/routers/dashboard.py Dashboard statistics endpoints
app/utils/risk_scorer.py Risk scoring algorithm

Starting the Backend

cd backend

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: .\venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set environment variables (optional)
export AUTO_CREATE_TABLES=true  # On Windows: set AUTO_CREATE_TABLES=true
export SQL_ECHO=false

# Start server
uvicorn app.main:app --reload

# Server runs on http://localhost:8000
# API docs at http://localhost:8000/docs

Environment Variables

Variable Default Description
DATABASE_URL sqlite:///./mcpshield.db Database connection string
JWT_SECRET Required - generate with python -c "import secrets; print(secrets.token_hex(32))" JWT signing key
ACCESS_TOKEN_EXPIRE_MINUTES 30 JWT expiration time
AUTO_CREATE_TABLES false Auto-create tables on startup
SQL_ECHO false Log SQL queries

Python Agent

Location

agent/

Key Files

File Purpose
mcpshield_agent/__init__.py Package version
mcpshield_agent/__main__.py Entry point for python -m
mcpshield_agent/cli.py Click CLI commands
mcpshield_agent/scanner.py MCP server discovery
mcpshield_agent/client.py API HTTP client
mcpshield_agent/config.py Configuration management

Installation

cd agent
pip install -e .

# Verify installation
mcpshield --version

Commands

Command Description
mcpshield configure --api-key KEY Configure agent with API key
mcpshield scan Scan and report MCP servers
mcpshield scan --dry-run Scan without reporting
mcpshield status Show agent status
mcpshield list List found servers locally

Config File Location

  • Windows: %LOCALAPPDATA%\MCPShield\config.json
  • macOS: ~/Library/Application Support/MCPShield/config.json
  • Linux: ~/.config/mcpshield/config.json

Scanned Locations

The agent scans these paths for MCP configurations:

Windows:

  • %APPDATA%\Claude\claude_desktop_config.json
  • %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
  • %APPDATA%\Windsurf\mcp_settings.json

macOS:

  • ~/Library/Application Support/Claude/claude_desktop_config.json

Linux:

  • ~/.config/Claude/claude_desktop_config.json
  • ~/.config/cursor/mcp.json

Frontend Dashboard

Location

frontend/

Key Files

File Purpose
app/layout.tsx Root layout with providers
app/page.tsx Landing page
app/login/page.tsx Login page
app/register/page.tsx Registration page
app/dashboard/layout.tsx Dashboard layout with auth
app/dashboard/page.tsx Dashboard overview
app/dashboard/servers/page.tsx Server list
app/dashboard/servers/[id]/page.tsx Server details
app/dashboard/agents/page.tsx Agent management
app/dashboard/alerts/page.tsx Alerts list
lib/api.ts API client
lib/auth-context.tsx Authentication context
components/dashboard/ Dashboard components

Starting the Frontend

cd frontend

# Install dependencies (first time)
npm install

# Start development server
npm run dev

# Server runs on http://localhost:3000

Environment Variables

Create .env.local:

NEXT_PUBLIC_API_URL=http://localhost:8000

Pages

Route Description Auth Required
/ Landing page No
/login User login No
/register User registration No
/dashboard Overview statistics Yes
/dashboard/servers All MCP servers Yes
/dashboard/servers/[id] Server details Yes
/dashboard/agents Agent management Yes
/dashboard/alerts Security alerts Yes
/dashboard/settings User settings Yes

Database Schema

Entity Relationship Diagram

┌─────────────────┐
│  Organization   │
├─────────────────┤
│ id (UUID) PK    │
│ name            │
│ alert_email     │
│ subscription_tier│
│ created_at      │
└────────┬────────┘
         │
         │ 1:N
         ▼
┌─────────────────┐         ┌─────────────────┐
│     User        │         │     Agent       │
├─────────────────┤         ├─────────────────┤
│ id (UUID) PK    │         │ id (UUID) PK    │
│ org_id FK       │         │ org_id FK       │
│ email           │         │ api_key         │
│ password_hash   │         │ name            │
│ full_name       │         │ hostname        │
│ role            │         │ os_type         │
│ is_active       │         │ username        │
│ created_at      │         │ ip_address      │
│ last_login      │         │ agent_version   │
└─────────────────┘         │ status          │
                            │ last_heartbeat  │
                            │ created_at      │
                            └────────┬────────┘
                                     │
                                     │ 1:N
                                     ▼
                            ┌─────────────────┐
                            │   MCPServer     │
                            ├─────────────────┤
                            │ id (UUID) PK    │
                            │ org_id FK       │
                            │ agent_id FK     │
                            │ server_name     │
                            │ server_type     │
                            │ command         │
                            │ scope           │
                            │ env_vars (JSON) │
                            │ status          │
                            │ risk_level      │
                            │ risk_score      │
                            │ risk_reason     │
                            │ risk_factors    │
                            │ is_verified     │
                            │ first_seen      │
                            │ last_seen       │
                            └────────┬────────┘
                                     │
                                     │ 1:N
                                     ▼
                            ┌─────────────────┐
                            │     Alert       │
                            ├─────────────────┤
                            │ id (UUID) PK    │
                            │ org_id FK       │
                            │ mcp_server_id FK│
                            │ alert_type      │
                            │ severity        │
                            │ title           │
                            │ description     │
                            │ is_dismissed    │
                            │ created_at      │
                            │ dismissed_at    │
                            └─────────────────┘

Models

All models use UUID primary keys with a custom TypeDecorator for PostgreSQL/SQLite compatibility.

Authentication & Security

Dual Authentication System

MCPShield uses two authentication methods:

1. JWT Tokens (Dashboard Users)

Header: Authorization: Bearer <jwt_token>
  • Used by web dashboard users
  • Issued on login/register
  • Contains user_id and org_id
  • Expires after 30 minutes (configurable)
  • Refresh tokens supported

2. API Keys (Agents)

Header: X-API-Key: mcp_sk_<32_random_chars>
  • Used by MCPShield agents
  • Generated when agent is created
  • Prefix: mcp_sk_ for identification
  • Never expires (until deleted)
  • Stored SHA-256 hashed in database

Multi-Tenancy

All data is scoped by org_id:

  • Every query filters by organization
  • Users can only see their organization's data
  • Agents belong to organizations
  • Servers are isolated between orgs

Password Security

  • Passwords hashed with bcrypt
  • Minimum 8 characters required
  • Salt automatically generated

Risk Scoring System

How Risk Scores Work

Each MCP server is assigned:

  • Risk Score: 0-100 numeric value
  • Risk Level: critical, high, medium, low
  • Risk Reason: Human-readable explanation
  • Risk Factors: List of contributing factors

Scoring Algorithm

Located in backend/app/utils/risk_scorer.py

def calculate_risk_score(server_data):
    score = 0
    factors = []
    
    # Command-based risks
    if contains_high_risk_command(command):
        score += 30
        factors.append("High-risk command detected")
    
    # Environment variable risks
    if has_sensitive_env_vars(env_vars):
        score += 25
        factors.append("Sensitive environment variables")
    
    # Scope/path risks
    if accesses_sensitive_paths(scope):
        score += 20
        factors.append("Access to sensitive paths")
    
    # Server type risks
    score += get_server_type_risk(server_type)
    
    return score, factors

Risk Level Thresholds

Score Level Color
85-100 Critical Purple
60-84 High Red
30-59 Medium Yellow
0-29 Low Green

Risk Factors Considered

  1. Command Analysis

    • Database clients (postgres, mysql, sqlite)
    • Docker/container access
    • Shell/bash execution
    • Network tools (curl, wget)

  2. Environment Variables

    • API keys (API_KEY, SECRET_KEY)
    • Database credentials (DATABASE_URL, PASSWORD)
    • Cloud credentials (AWS_, AZURE_)

  3. Scope/Path Analysis

    • Home directory access
    • System directories
    • Sensitive file paths

  4. Server Type

    • Filesystem servers
    • Database connectors
    • Code execution servers

Local Development Setup

Prerequisites

  • Python 3.11+
  • Node.js 18+
  • Git

Complete Setup

# Clone or navigate to project
cd d:\mcpshield

# ============ BACKEND ============
cd backend

# Create virtual environment
python -m venv venv
.\venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Start backend
set AUTO_CREATE_TABLES=true
uvicorn app.main:app --reload
# Running on http://localhost:8000

# ============ AGENT ============
cd ..\agent

# Install agent in development mode
pip install -e .

# Verify
mcpshield --version

# ============ FRONTEND ============
cd ..\frontend

# Install dependencies
npm install

# Create env file
echo NEXT_PUBLIC_API_URL=http://localhost:8000 > .env.local

# Start frontend
npm run dev
# Running on http://localhost:3000

Running All Services

You need 2 terminal windows:

Terminal 1 - Backend:

cd d:\mcpshield\backend
.\venv\Scripts\activate
uvicorn app.main:app --reload

Terminal 2 - Frontend:

cd d:\mcpshield\frontend
npm run dev

Testing

Backend API Tests

Located in backend/tests/

cd d:\mcpshield\backend
.\venv\Scripts\activate
pytest

Manual API Testing

A test script is available at backend/test_api.py:

cd d:\mcpshield\backend
.\venv\Scripts\python test_api.py

This tests:

  1. Health check
  2. User registration
  3. Agent creation
  4. Agent heartbeat
  5. MCP server reporting
  6. Dashboard stats
  7. Server listing

Agent Testing

# Configure with test API key
mcpshield configure --api-key mcp_sk_YOUR_KEY --api-url http://localhost:8000

# Dry run (no API call)
mcpshield scan --dry-run

# Full scan with reporting
mcpshield scan

# Check status
mcpshield status

Frontend Testing

cd d:\mcpshield\frontend
npm run build  # Check for build errors

Project Structure

d:\mcpshield\
├── backend/
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py              # FastAPI app entry point
│   │   ├── database.py          # Database configuration
│   │   ├── models.py            # SQLAlchemy models
│   │   ├── schemas.py           # Pydantic schemas
│   │   ├── auth.py              # Authentication helpers
│   │   ├── routers/
│   │   │   ├── auth.py          # /auth endpoints
│   │   │   ├── agents.py        # /agents endpoints
│   │   │   ├── mcp.py           # /mcp endpoints
│   │   │   ├── alerts.py        # /alerts endpoints
│   │   │   └── dashboard.py     # /dashboard endpoints
│   │   └── utils/
│   │       └── risk_scorer.py   # Risk scoring logic
│   ├── alembic/                 # Database migrations
│   ├── tests/                   # Test files
│   ├── requirements.txt
│   ├── test_api.py              # API test script
│   └── mcpshield.db             # SQLite database (dev)
│
├── agent/
│   ├── mcpshield_agent/
│   │   ├── __init__.py          # Package info
│   │   ├── __main__.py          # Entry point
│   │   ├── cli.py               # CLI commands
│   │   ├── scanner.py           # MCP discovery
│   │   ├── client.py            # API client
│   │   └── config.py            # Config management
│   ├── setup.py                 # Package setup
│   ├── requirements.txt
│   └── README.md
│
├── frontend/
│   ├── app/
│   │   ├── layout.tsx           # Root layout
│   │   ├── page.tsx             # Landing page
│   │   ├── globals.css          # Global styles
│   │   ├── login/
│   │   │   └── page.tsx         # Login page
│   │   ├── register/
│   │   │   └── page.tsx         # Register page
│   │   └── dashboard/
│   │       ├── layout.tsx       # Dashboard layout
│   │       ├── page.tsx         # Overview
│   │       ├── servers/
│   │       │   ├── page.tsx     # Server list
│   │       │   └── [id]/
│   │       │       └── page.tsx # Server details
│   │       ├── agents/
│   │       │   └── page.tsx     # Agent management
│   │       ├── alerts/
│   │       │   └── page.tsx     # Alerts
│   │       └── settings/
│   │           └── page.tsx     # Settings
│   ├── components/
│   │   ├── dashboard/           # Dashboard components
│   │   └── ui/                  # UI components
│   ├── lib/
│   │   ├── api.ts               # API client
│   │   ├── auth-context.tsx     # Auth provider
│   │   ├── providers.tsx        # App providers
│   │   └── utils.ts             # Utilities
│   ├── package.json
│   ├── tailwind.config.ts
│   └── .env.local               # Environment config
│
└── DOCUMENTATION.md             # This file

API Reference

Base URL

http://localhost:8000/api/v1

Authentication Endpoints

Register User

POST /auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "org_name": "My Organization",
  "full_name": "John Doe"  // optional
}

Response: 201 Created
{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer",
  "user": { ... },
  "organization": { ... }
}

Login

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePassword123!"
}

Response: 200 OK
{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer",
  "user": { ... }
}

Get Current User

GET /auth/me
Authorization: Bearer <token>

Response: 200 OK
{
  "id": "uuid",
  "email": "user@example.com",
  "full_name": "John Doe",
  "role": "admin",
  ...
}

Agent Endpoints

Create Agent

POST /agents/
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "My Agent"  // optional
}

Response: 201 Created
{
  "agent_id": "uuid",
  "api_key": "mcp_sk_..."
}

List Agents

GET /agents/
Authorization: Bearer <token>

Response: 200 OK
[
  {
    "id": "uuid",
    "name": "Work Laptop",
    "hostname": "DESKTOP-123",
    "status": "active",
    "last_heartbeat": "2026-01-23T...",
    "mcp_server_count": 3,
    ...
  }
]

Agent Heartbeat

POST /agents/heartbeat
X-API-Key: mcp_sk_...
Content-Type: application/json

{
  "hostname": "DESKTOP-123",
  "os_type": "windows",
  "username": "david",
  "ip_address": "192.168.1.100",
  "agent_version": "0.1.0"
}

Response: 200 OK
{ ... agent details ... }

MCP Server Endpoints

Report Servers

POST /mcp/report
X-API-Key: mcp_sk_...
Content-Type: application/json

{
  "servers": [
    {
      "server_name": "filesystem",
      "server_type": "@modelcontextprotocol/server-filesystem",
      "command": "npx -y @modelcontextprotocol/server-filesystem /home/user",
      "scope": "/home/user",
      "env_vars": ["API_KEY"],
      "status": "active"
    }
  ]
}

Response: 200 OK
{
  "created": 1,
  "updated": 0,
  "alerts": 0,
  "servers": [ ... ]
}

List Servers

GET /mcp/servers?risk_level=high&status=active&page=1&page_size=10
Authorization: Bearer <token>

Response: 200 OK
{
  "servers": [ ... ],
  "total": 25,
  "page": 1,
  "page_size": 10
}

Get Server Details

GET /mcp/servers/{id}
Authorization: Bearer <token>

Response: 200 OK
{
  "id": "uuid",
  "server_name": "filesystem",
  "risk_level": "medium",
  "risk_score": 35,
  ...
}

Dashboard Endpoints

Get Statistics

GET /dashboard/stats
Authorization: Bearer <token>

Response: 200 OK
{
  "total_servers": 5,
  "critical_risk_count": 0,
  "high_risk_count": 1,
  "medium_risk_count": 3,
  "low_risk_count": 1,
  "active_agents": 2,
  "total_agents": 2,
  "recent_alerts": 0
}

Get Top Risks

GET /dashboard/top-risks?limit=5
Authorization: Bearer <token>

Response: 200 OK
[ ... top 5 highest risk servers ... ]

Alert Endpoints

List Alerts

GET /alerts/?is_dismissed=false&severity=high
Authorization: Bearer <token>

Response: 200 OK
[ ... alerts ... ]

Dismiss Alert

POST /alerts/{id}/dismiss
Authorization: Bearer <token>

Response: 200 OK
{ ... updated alert ... }

Current Status

Completed Features

Component Feature Status
Backend FastAPI application ✅ Complete
User registration/login ✅ Complete
JWT authentication ✅ Complete
Agent API key auth ✅ Complete
Multi-tenant data isolation ✅ Complete
MCP server CRUD ✅ Complete
Risk scoring algorithm ✅ Complete
Dashboard statistics ✅ Complete
Alerts system ✅ Complete
SQLite support ✅ Complete
PostgreSQL support ✅ Complete
Agent CLI interface ✅ Complete
MCP config discovery ✅ Complete
Windows support ✅ Complete
macOS/Linux paths ✅ Complete
API communication ✅ Complete
Heartbeat reporting ✅ Complete
Frontend Landing page ✅ Complete
Login/Register ✅ Complete
Auth context ✅ Complete
Dashboard overview ✅ Complete
Server list ✅ Complete
Server details ✅ Complete
Agent management ✅ Complete
Settings page ✅ Basic

Tested Flows

Flow Status
User registration → Login → Dashboard ✅ Tested
Agent creation → Get API key ✅ Tested
Agent scan → Report servers → View in dashboard ✅ Tested
Risk score calculation ✅ Tested
Server verification ✅ Tested

Known Limitations

  1. No real-time updates: Dashboard requires manual refresh
  2. No email notifications: Alerts are display-only
  3. No scheduled scanning: Agent runs manually
  4. Basic risk scoring: Could be more sophisticated
  5. No audit logging: User actions not logged

Next Steps

Immediate (Before Launch)

  • Add loading states to all pages
  • Improve error handling
  • Add toast notifications
  • Test all edge cases
  • Security audit

Short Term (Post-Launch)

  • Scheduled agent scanning
  • Email notifications for alerts
  • Webhook integrations
  • Agent auto-update
  • Real-time WebSocket updates

Medium Term

  • Team management (invite users)
  • RBAC (role-based access control)
  • Audit logging
  • Custom risk rules
  • API rate limiting (slowapi, 10/min on /mcp/report, 5/min on auth)

Long Term

  • SOC2 compliance features
  • SSO/SAML authentication
  • Advanced analytics
  • Mobile app
  • Enterprise deployment options

Support

Getting Help

  1. Check this documentation
  2. Review API docs at /docs
  3. Check backend logs for errors
  4. Verify database connectivity

Common Issues

Backend won't start:

  • Check if port 8000 is in use
  • Verify Python virtual environment is activated
  • Check database connection string

Frontend shows blank page:

  • Check browser console for errors
  • Verify backend is running
  • Check .env.local configuration

Agent can't connect:

  • Verify API URL is correct
  • Check API key format (mcp_sk_...)
  • Ensure backend is running

Documentation generated April 2026