Architecture

Architecture

System Overview

MCPShield uses a three-tier architecture with a Python agent for discovery, FastAPI backend for processing, and Next.js frontend for visualization.

┌─────────────────────────────────────────────────────────────────────┐
│                         MCPShield Architecture                       │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐        │
│  │   Machine 1  │     │   Machine 2  │     │   Machine N  │        │
│  │              │     │              │     │              │        │
│  │ ┌──────────┐ │     │ ┌──────────┐ │     │ ┌──────────┐ │        │
│  │ │  Agent   │ │     │ │  Agent   │ │     │ │  Agent   │ │        │
│  │ └────┬─────┘ │     │ └────┬─────┘ │     │ └────┬─────┘ │        │
│  └──────┼───────┘     └──────┼───────┘     └──────┼───────┘        │
│         │                    │                    │                 │
│         └────────────────────┼────────────────────┘                 │
│                              │ HTTPS                                │
│                              ▼                                      │
│                   ┌─────────────────────┐                          │
│                   │   MCPShield API     │                          │
│                   │   (FastAPI/Python)  │                          │
│                   └──────────┬──────────┘                          │
│                              │                                      │
│                              ▼                                      │
│                   ┌─────────────────────┐                          │
│                   │     Database        │                          │
│                   │  (PostgreSQL/SQLite)│                          │
│                   └──────────┬──────────┘                          │
│                              │                                      │
│                              ▼                                      │
│                   ┌─────────────────────┐                          │
│                   │  Frontend Dashboard │                          │
│                   │    (Next.js/React)  │                          │
│                   └─────────────────────┘                          │
└─────────────────────────────────────────────────────────────────────┘

Components

Agent (Python CLI)

• Scans for MCP configuration files
• Detects running MCP server processes
• Reports discovered servers to backend
• Stores configuration locally

Backend (FastAPI)

• RESTful API endpoints
• JWT authentication for users
• API key authentication for agents
• Risk scoring engine
• Multi-tenant data isolation

Frontend (Next.js)

• Server-side rendered React
• Real-time dashboard
• Server management UI
• Alert notifications

Database

• PostgreSQL (production)
• SQLite (development)
• 5 core tables: Organizations, Users, Agents, MCPServers, Alerts

Data Flow

1. Agent Installation: User installs agent via pip install -e .
2. Configuration: Agent configured with API key from dashboard
3. Discovery: Agent scans known MCP config locations
4. Reporting: Agent sends server data via POST /mcp/report
5. Risk Assessment: Backend calculates risk scores
6. Visualization: Dashboard displays servers and alerts

Security

• All API communication over HTTPS
• JWT tokens expire in 30 minutes
• API keys scoped to single agent
• Organization-level data isolation
• Password hashing with bcrypt