Architecture - SuperMCP

System Overview

forge-mcptools is built on a microservices architecture with three main layers:

┌─────────────────────────────────────────────────────────────┐
│                         User Layer                           │
│  ┌──────────────────┐            ┌──────────────────┐       │
│  │  Web Dashboard   │            │   API Clients    │       │
│  │  (React:3000)    │            │   (REST/SDK)     │       │
│  └────────┬─────────┘            └────────┬─────────┘       │
└───────────┼──────────────────────────────┼─────────────────┘
            │                              │
┌───────────┴──────────────────────────────┴─────────────────┐
│                    Application Layer                         │
│  ┌─────────────────────────────────────────────────────┐    │
│  │         Backend API (FastAPI:8000)                  │    │
│  │  • Authentication & Authorization                   │    │
│  │  • Connector Registry                               │    │
│  │  • Server Management                                │    │
│  │  • Tool Orchestration                               │    │
│  │  • PostgreSQL Database                              │    │
│  └────────┬───────────────────────────────────────────┘    │
└───────────┼──────────────────────────────────────────────┘
            │
┌───────────┴──────────────────────────────────────────────┐
│                    Connector Layer                         │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────┐     │
│  │  PostgreSQL  │  │    MSSQL     │  │   Custom    │     │
│  │  Connector   │  │  Connector   │  │ Connectors  │     │
│  │  (:8027)     │  │  (:8028)     │  │  (:8029+)   │     │
│  └──────┬───────┘  └──────┬───────┘  └──────┬──────┘     │
└─────────┼──────────────────┼──────────────────┼──────────┘
          │                  │                  │
┌─────────┴──────────────────┴──────────────────┴──────────┐
│                       Data Layer                           │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────┐     │
│  │  PostgreSQL  │  │  SQL Server  │  │    MySQL    │     │
│  │   Database   │  │  / Azure SQL │  │   Database  │     │
│  └──────────────┘  └──────────────┘  └─────────────┘     │
└────────────────────────────────────────────────────────────┘

Detailed Architecture Diagram

The following diagram illustrates the complete system architecture showing how MCP clients, the dashboard, connectors, and data layers interact: SuperMCP Architecture Diagram

Architecture Components

Dashboard & MCP Clients

User Interfaces

Dashboard: Web-based UI for managing connectors and servers
MCP Client/AI Agents: AI assistants like Claude, Cursor that connect via MCP protocol

Both interfaces communicate with the Application Layer below.

Application Layer

Central Orchestration

Routes requests between clients and connectors
Manages authentication and authorization
Handles server lifecycle and configuration
Maintains connector registry

Postgres Connector

PostgreSQL Integration

MCP PG Server 1, 2, …: Multiple server instances
Each MCP server connects to its corresponding PostgreSQL database
Supports multiple isolated database connections
Independent connection pools per server

MySQL Connector

MySQL Integration

MCP Msql Server 1, 2, …: Multiple server instances
Each MCP server connects to its corresponding MySQL database
Isolated connections for multi-tenant scenarios
Per-server connection management

Data Layer

Target Databases

PostgreSQL databases (Pg server 1, 2, …)
MySQL databases (Msql server 1, 2, …)
Each connector can manage multiple database instances
Secure, encrypted connections

Key Architectural Patterns

Multi-Server Support

Single connector managing multiple server instances with independent configurations

Loose Coupling

Connectors and application layer communicate via REST APIs for flexibility

MCP Protocol

Standardized Model Context Protocol for AI agent integration

Scalability

Each connector scales independently based on load

Core Components

1. Backend API (FastAPI)

Purpose: Central orchestration and management Key Responsibilities:

User authentication (JWT tokens)
Connector registration and discovery
Server lifecycle management
Tool routing and execution
Configuration storage

Technology Stack:

Framework: FastAPI (Python)
Database: PostgreSQL
ORM: SQLAlchemy
Auth: FastAPI Users with JWT
Migrations: Alembic

Port: 8000 (configurable)

2. Frontend Dashboard (React)

Purpose: User interface for management and monitoring Key Features:

Connector management interface
Server creation and configuration
Tool playground with parameter input
Real-time status monitoring
User account management

Technology Stack:

Framework: React 18
State Management: React Query
Styling: Tailwind CSS
HTTP Client: Axios
Build Tool: Vite

Port: 3000 (configurable)

3. Connectors (FastMCP)

Purpose: Data source adapters with MCP protocol Common Features:

Connection pooling
Async operations
Schema introspection
Query execution
Health monitoring

Technology Stack:

Framework: FastMCP (MCP implementation)
Server: Uvicorn (ASGI)
Validation: Pydantic
Package Manager: UV

Ports: 8027, 8028, 8029, … (one per connector)

Data Flow

1. Tool Execution Flow

User Request

User invokes a tool via dashboard or API

POST /api/v1/tools/execute
{
  "server_id": "server-123",
  "tool_name": "list_tables",
  "parameters": {}
}

Authentication

Backend validates JWT token and user permissions

Server Lookup

Backend retrieves server configuration and connector endpoint

Connector Invocation

Backend forwards request to connector service

POST http://localhost:8027/tools/list_tables

Data Access

Connector executes operation on target data source

Response

Results flow back through backend to user

2. Server Creation Flow

User → Dashboard → Backend API → Database
                      ↓
               Connector Registry
                      ↓
            Server Configuration Stored

Component Communication

Backend ↔ Connectors

Protocol: HTTP/REST Authentication: Internal API keys (optional) Endpoints:

GET  /health              - Health check
POST /tools/{tool_name}   - Execute tool
GET  /tools               - List available tools
GET  /config             - Get connector metadata

Frontend ↔ Backend

Protocol: HTTP/REST with JSON Authentication: JWT Bearer tokens Key Endpoints:

POST /auth/login          - User authentication
GET  /connectors          - List registered connectors
POST /servers             - Create server instance
GET  /servers/{id}/tools  - List server tools
POST /tools/execute       - Execute tool

Database Schema

Backend Database (PostgreSQL)

users
├── id (UUID, PK)
├── email (VARCHAR, UNIQUE)
├── hashed_password (VARCHAR)
├── is_active (BOOLEAN)
└── is_superuser (BOOLEAN)

connectors
├── id (UUID, PK)
├── name (VARCHAR)
├── type (VARCHAR)
├── endpoint (VARCHAR)
├── status (VARCHAR)
├── created_at (TIMESTAMP)
└── config_schema (JSONB)

servers
├── id (UUID, PK)
├── connector_id (UUID, FK)
├── name (VARCHAR)
├── configuration (JSONB)
├── status (VARCHAR)
├── created_by (UUID, FK → users.id)
└── created_at (TIMESTAMP)

tools
├── id (UUID, PK)
├── connector_id (UUID, FK)
├── name (VARCHAR)
├── description (TEXT)
└── parameters_schema (JSONB)

Connection Pooling Architecture

Each connector implements intelligent connection pooling:

Connector Service
  ↓
PoolManager
├── Global Connection Limit (500)
├── Per-Server Pools
│   ├── Server A: Pool (size: 5, max: 10)
│   ├── Server B: Pool (size: 5, max: 10)
│   └── Server C: Pool (size: 5, max: 10)
├── LRU Eviction
└── Idle Cleanup (TTL: 300s)

Pool Configuration

# asyncpg pool
pool = await asyncpg.create_pool(
    host=config.host,
    port=config.port,
    database=config.database,
    user=config.username,
    password=config.password,
    min_size=0,
    max_size=5
)

Security Architecture

Authentication Flow

1. User Login
   ↓
2. Backend validates credentials
   ↓
3. Generate JWT (access + refresh tokens)
   ↓
4. Client stores tokens
   ↓
5. Subsequent requests include Bearer token
   ↓
6. Backend validates token on each request

Authorization Layers

User Level

Active vs inactive users
Superuser privileges
Email verification

Server Level

Per-server access control
Creator ownership
Shared access (future)

Tool Level

Read-only tools
Write/modify tools
Admin-only tools

Connector Level

SSL/TLS encryption
Credential encryption
Connection string security

Scalability Considerations

Horizontal Scaling

Backend
Connectors
Database

Stateless API design
Session store in database
Load balancer ready
Multiple instances possible

Performance Optimizations

Connection Pooling: Reuse database connections
Async Operations: Non-blocking I/O throughout
Query Caching: Frequently accessed data cached
Lazy Loading: Tools loaded on-demand
Response Streaming: Large results streamed

Deployment Architectures

Development

Docker Compose
├── Backend (hot reload)
├── Frontend (Vite dev server)
├── PostgreSQL (database)
├── Connector 1
└── Connector 2

Production

Kubernetes/Docker Swarm
├── Load Balancer
├── Backend (3 replicas)
├── Frontend (static files via CDN)
├── PostgreSQL (managed service)
└── Connectors (auto-scaled)

Monitoring & Observability

Health Checks

Each service exposes /health endpoint

Logging

Structured logging with levels (DEBUG, INFO, ERROR)

Metrics

Connection pool stats, request latency, error rates

Tracing

Request ID tracking across services

Technology Decisions

Why FastAPI?

Automatic OpenAPI documentation
Native async/await support
Type validation with Pydantic
High performance (Starlette/Uvicorn)
Easy testing

Why React?

Component-based architecture
Rich ecosystem
Excellent developer experience
Strong TypeScript support
Large community

Why PostgreSQL?

JSONB for flexible schemas
Excellent performance
ACID compliance
Rich feature set
Wide adoption

Why FastMCP?

MCP protocol implementation
Tool registration framework
Async-first design
Minimal overhead
Python ecosystem

Getting started

Development

​System Overview

​Detailed Architecture Diagram

​Architecture Components

​Key Architectural Patterns

Multi-Server Support

Loose Coupling

MCP Protocol

Scalability

​Core Components

​1. Backend API (FastAPI)

​2. Frontend Dashboard (React)

​3. Connectors (FastMCP)

​Data Flow

​1. Tool Execution Flow

​2. Server Creation Flow

​Component Communication

​Backend ↔ Connectors

​Frontend ↔ Backend

​Database Schema

​Backend Database (PostgreSQL)

​Connection Pooling Architecture

​Pool Configuration

​Security Architecture

​Authentication Flow

​Authorization Layers

User Level

Server Level

Tool Level

Connector Level

​Scalability Considerations

​Horizontal Scaling

​Performance Optimizations

​Deployment Architectures

​Development

​Production

​Monitoring & Observability

Health Checks

Logging

Metrics

Tracing

​Technology Decisions

​Why FastAPI?

​Why React?

​Why PostgreSQL?

​Why FastMCP?

​Next Steps

Build a Connector

Local Setup

System Overview

Detailed Architecture Diagram

Architecture Components

Key Architectural Patterns

Core Components

1. Backend API (FastAPI)

2. Frontend Dashboard (React)

3. Connectors (FastMCP)

Data Flow

1. Tool Execution Flow

2. Server Creation Flow

Component Communication

Backend ↔ Connectors

Frontend ↔ Backend

Database Schema

Backend Database (PostgreSQL)

Connection Pooling Architecture

Pool Configuration

Security Architecture

Authentication Flow

Authorization Layers

Scalability Considerations

Horizontal Scaling

Performance Optimizations

Deployment Architectures

Development

Production

Monitoring & Observability

Technology Decisions

Why FastAPI?

Why React?

Why PostgreSQL?

Why FastMCP?

Next Steps