Skip to main content

Architecture Overview

Learn about the architecture and design principles of MCP Gatekeeper.

System Architecture​

MCP Gatekeeper is built as a Turborepo monorepo with a clear separation between backend and frontend:

┌─────────────────────────────────────────────────────────────┐
│                         Browser                              │
│  ┌────────────────────────────────────────────────────┐    │
│  │  React Frontend (Port 5173)                        │    │
│  │  - Material-UI Components                          │    │
│  │  - Real-time WebSocket Client                      │    │
│  │  - Theme System (Light/Dark)                       │    │
│  └────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                           ▲
                           │ HTTP / WebSocket
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                    Backend (127.0.0.1:8000)                  │
│  ┌────────────────────────────────────────────────────┐    │
│  │  FastAPI Application                               │    │
│  │  ┌──────────────┬──────────────┬─────────────┐   │    │
│  │  │   REST API   │  WebSocket   │  Auth Layer │   │    │
│  │  └──────────────┴──────────────┴─────────────┘   │    │
│  └────────────────────────────────────────────────────┘    │
│  ┌────────────────────────────────────────────────────┐    │
│  │  Services                                          │    │
│  │  ┌──────────────┬──────────────┬─────────────┐   │    │
│  │  │  Package     │  Agent       │  MCP Client │   │    │
│  │  │  Manager     │  Scanner     │  (JSON-RPC) │   │    │
│  │  └──────────────┴──────────────┴─────────────┘   │    │
│  └────────────────────────────────────────────────────┘    │
│  ┌────────────────────────────────────────────────────┐    │
│  │  Database (SQLite)                                 │    │
│  │  - Servers, Metrics, Logs, Events                 │    │
│  └────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                    MCP Server Processes                      │
│  ┌─────────────┬─────────────┬─────────────┐               │
│  │  Server 1   │  Server 2   │  Server N   │               │
│  │  (STDIO)    │  (STDIO)    │  (STDIO)    │               │
│  └─────────────┴─────────────┴─────────────┘               │
└─────────────────────────────────────────────────────────────┘

Core Components​

Frontend (apps/frontend/)​

Technology Stack:

  • React 19 + TypeScript
  • Vite (build tool)
  • Material-UI (MUI) v6
  • React Router v7
  • Axios for HTTP requests
  • Recharts for visualizations

Key Features:

  • 9 page components (Dashboard, Servers, Stdio Servers, HTTP Servers, Agents, Metrics, Logs, ServerDetail, ServerActivity)
  • 9 reusable components (Layout, ErrorBoundary, FilterBar, TerminalViewer, etc.)
  • Dark/Light theme system with persistent preferences
  • Real-time WebSocket updates
  • Responsive design with accessibility features

Backend (apps/backend/)​

Technology Stack:

  • Python 3.9+
  • FastAPI (async web framework)
  • SQLAlchemy (ORM)
  • SQLite (database)
  • Pydantic (validation)
  • asyncio for async operations

Key Components:

  • REST API endpoints for CRUD operations
  • WebSocket server for real-time updates
  • Token-based authentication
  • MCP client for JSON-RPC communication (STDIO)
  • HTTP proxy for remote MCP servers
  • Package manager for npm integration
  • Agent configuration scanner
  • Metrics collection and aggregation

Data Flow​

Package Installation Flow​

User → Frontend → POST /api/packages/install-npm
              ↓
         Backend API
              ↓
      Package Manager Service
              ↓
      npm install (subprocess)
              ↓
      Binary Replacer (STDIO wrapper)
              ↓
      Database (record package)
              ↓
      Response → Frontend → User

Real-time Metrics Flow​

MCP Server → STDIO Wrapper → POST /api/metrics/record
                                      ↓
                              Store in Database
                                      ↓
                              Broadcast via WebSocket
                                      ↓
                              Frontend Updates UI

Agent Configuration Flow​

User → Frontend → PUT /api/agents/{agent_type}/servers
              ↓
         Backend API
              ↓
    Agent Config Scanner
              ↓
    Read JSON Config File
              ↓
    Modify mcpServers section
              ↓
    Write JSON Config File
              ↓
    Response → Frontend → User

Design Principles​

Security First​

  • Local-only binding: Backend binds to 127.0.0.1
  • Token authentication: Protected endpoints require auth
  • Input validation: All inputs validated with Pydantic
  • CORS configuration: Restricted to localhost origins

Real-time Updates​

  • WebSocket communication: Live metrics and logs
  • Event-driven architecture: Push updates to clients
  • Efficient polling: Minimal resource usage

Developer Experience​

  • Beautiful UI: Modern Material-UI design
  • Clear feedback: Loading states, error messages
  • Type safety: TypeScript throughout frontend
  • API documentation: Auto-generated OpenAPI docs

Scalability​

  • Monorepo structure: Easy to add new apps
  • Turborepo caching: Fast builds and deploys
  • Service separation: Clear boundaries
  • Database abstraction: Easy to switch databases

Technology Choices​

Why FastAPI?​

  • Async support: Handle concurrent connections efficiently
  • Auto documentation: OpenAPI/Swagger built-in
  • Type hints: Pydantic validation
  • WebSocket support: Built-in WebSocket capabilities
  • Performance: One of the fastest Python frameworks

Why React + MUI?​

  • Rich ecosystem: Extensive component library
  • Accessibility: ARIA support out of the box
  • Theming: Powerful theme customization
  • TypeScript: Full type safety
  • Community: Large, active community

Why Turborepo?​

  • Monorepo management: Handle multiple apps
  • Build caching: Speed up CI/CD
  • Task orchestration: Run tasks in parallel
  • Incremental adoption: Add gradually

Why SQLite?​

  • Zero configuration: No database server needed
  • Local storage: Perfect for local development
  • ACID compliant: Reliable transactions
  • Portable: Single file database
  • Upgradable: Can switch to PostgreSQL later

Next Steps​