Architecture

Architecture

System Overview

MCPShield uses a three-tier architecture: a Python agent for discovery, a FastAPI backend for processing and risk scoring, and a Next.js dashboard for visualization.

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 -->|pip install + scan| agent
    agent -->|X-API-Key| backend
    backend -->|JWT| ui

Loading

API Layer

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

Loading

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
    }

Loading

Components

Agent (Python CLI)

• Scans for MCP configuration files across Claude Desktop, Cursor, Windsurf, and custom paths
• Skips re-scans when config file mtimes are unchanged (minimal CPU overhead)
• Captures environment variable names only — never values or secrets
• Reports to backend via HTTPS using a per-agent API key

Backend (FastAPI)

• RESTful API with domain routers: auth, agents, mcp, alerts, dashboard
• JWT authentication (30 min access / 7 day refresh) for web users
• SHA-256 hashed API key authentication for agents
• Risk scoring engine with compiled-regex pattern matching
• Multi-tenant: all data is scoped to an org_id

Frontend (Next.js 14)

• App Router with client-side auth context
• TTL-cached API client to reduce unnecessary requests
• Global command palette (Cmd/Ctrl+K) for searching servers and alerts
• Dashboard, Servers, Alerts, Agents, and Settings pages

Database

• PostgreSQL in production, SQLite for local development
• Alembic migrations for schema management
• 5 core tables: Organizations → Users → Agents → MCPServers → Alerts

Security

• All agent-to-backend communication over HTTPS
• JWT access tokens expire in 30 minutes
• API keys are scoped to a single agent and stored as SHA-256 hashes
• Organization-level data isolation — no cross-org data access possible
• Passwords hashed with bcrypt
• CORS configured per deployment