# aarora79/mcp-gateway architecture

> Architecture diagram of the GitHub repository aarora79/mcp-gateway, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aarora79/mcp-gateway
- Repository: https://github.com/aarora79/mcp-gateway

## Overview

##### Project Type & Purpose
- This is a full-stack, containerized microservice application that implements an MCP (Model Context Protocol) Gateway and Registry.
- The Gateway is an Nginx reverse-proxy that fronts one or more MCP servers (local Python “servers/*” services, remote EKS/EKS-backed services, or API Gateway+Lambda).
- The Registry is a FastAPI/Uvicorn app (registry/main.py) with Jinja2 templates (registry/templates), static assets, health‐check scheduler, dynamic Nginx config generator, and a web UI that manages and monitors the MCP servers.

##### File Structure Clues
- Top‐level Dockerfile, docker/entrypoint.sh, nginx_rev_proxy.conf → container + reverse proxy.
- registry/ → Registry app, templates, static CSS, server metadata files, Nginx config template.
- servers/* → Sample MCP servers (currenttime, fininfo, mcpgw, realserverfaketools), each with server.py and client.py.
- agents/agent.py → example AI Agent using MCP clients.
- build_and_push.sh, .github/workflows → CI/CD and container build scripts.

##### Main Components
a. AI Agents (agents/agent.py or any external agent)
b. Gateway & Registry container
– Nginx Reverse Proxy (docker/nginx_rev_proxy.conf)
– FastAPI/Uvicorn app (registry/main.py)
– Jinja2 Web UI (registry/templates + registry/static)
– Background health-check/task scheduler (periodically polls /sse on each service)
– Dynamic Nginx config generator (registry/nginx_mcp_revproxy.conf → Nginx reload)
– File-based state store (registry/servers/*.json + registry/server_state.json)
c. Local MCP Servers (servers/currenttime, fininfo, mcpgw, realserverfaketools)
d. Remote MCP Services (EKS cluster or API Gateway + AWS Lambda, optional)
e. External Data Sources & APIs (Polygon API, databases, third-party APIs)

##### Relationships & Data Flows
- AI Agent → (MCP Protocol, SSE or streamable HTTP) → Nginx Reverse Proxy → multiplex routes to the correct MCP Server.
- MCP Server → responds via SSE/HTTP streaming → Nginx → back to Agent.
- Registry UI → (HTTP & WebSocket /ws/health_status) → Uvicorn app → serves HTML, JSON, WebSocket updates.
- Background task in Registry → polls each service’s /sse health endpoint → updates server_state.json → regenerates registry/nginx_mcp_revproxy.conf → triggers Nginx reload.
- MCP Servers → interact with external data sources (Polygon API, DBs, external APIs).

##### Architectural Patterns & Design Principles
- Microservices: Each MCP server is an independent Python service.
- Reverse-proxy pattern: Nginx routes based on path (/currenttime, /fininfo, etc.).
- MVC‐like Registry:
– Model: JSON metadata, server_state.json
– View: Jinja2 templates, static CSS, JS for WebSocket updates
– Controller: FastAPI endpoints, WebSocket endpoint, register/edit/toggle APIs
- Dynamic configuration: The Registry writes Nginx config fragments based on enabled/disabled services.
- Containerization & DevOps: Dockerfile, build_and_push.sh, CI workflows, .dockerignore.
- Event-driven updates: WebSockets for real-time UI updates on health status.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Agents
    subgraph "Agents"
        Agent["AI Agent"]:::agent
    end

    %% Gateway & Registry Container
    subgraph "Gateway & Registry Container"
        direction TB
        Nginx["Nginx Reverse Proxy"]:::gateway
        Entrypoint["Entrypoint Script"]:::gateway
        DockerfileNode["Dockerfile"]:::gateway

        subgraph "Registry App"
            direction TB
            FastAPI["FastAPI/Uvicorn App"]:::registry
            UI["Jinja2 Web UI"]:::registry
            Static["Static Assets"]:::registry
            Scheduler["Health-Check Scheduler"]:::registry
            ConfigGen["Dynamic Nginx Config Generator"]:::registry
            StateStore["Server State Store"]:::datastore
        end
    end

    %% Local MCP Servers
    subgraph "Local MCP Servers"
        direction TB
        CT["currenttime Service"]:::server
        FI["fininfo Service"]:::server
        MG["mcpgw Service"]:::server
        RS["realserverfaketools Service"]:::server
    end

    %% Remote MCP Services
    subgraph "Remote MCP Services"
        EKS["EKS/API GW+Lambda"]:::cloud
    end

    %% External Systems & APIs
    subgraph "External Systems & APIs"
        Polygon["Polygon API"]:::external
        DB["Databases & Third-Party APIs"]:::external
    end

    %% Relationships
    Agent -->|"SSE/Streamable HTTP"| Nginx
    Nginx -->|"/currenttime"| CT
    Nginx -->|"/fininfo"| FI
    Nginx -->|"/mcpgw"| MG
    Nginx -->|"/realserverfaketools"| RS
    Nginx -->|"/remote"| EKS

    CT -->|"Tool Connection"| Polygon
    CT -->|"Tool Connection"| DB
    FI -->|"Tool Connection"| Polygon
    FI -->|"Tool Connection"| DB
    MG -->|"Tool Connection"| Polygon
    MG -->|"Tool Connection"| DB
    RS -->|"Tool Connection"| Polygon
    RS -->|"Tool Connection"| DB

    UI <-->|"HTTP/WebSocket"| FastAPI
    Scheduler -->|"poll /sse"| CT
    Scheduler -->|"poll /sse"| FI
    Scheduler -->|"poll /sse"| MG
    Scheduler -->|"poll /sse"| RS
    Scheduler --> StateStore
    StateStore --> ConfigGen
    ConfigGen --> Nginx

    %% Click Events
    click Agent "https://github.com/aarora79/mcp-gateway/blob/main/agents/agent.py"
    click Nginx "https://github.com/aarora79/mcp-gateway/blob/main/docker/nginx_rev_proxy.conf"
    click Entrypoint "https://github.com/aarora79/mcp-gateway/blob/main/docker/entrypoint.sh"
    click DockerfileNode "https://github.com/aarora79/mcp-gateway/tree/main/Dockerfile"
    click FastAPI "https://github.com/aarora79/mcp-gateway/blob/main/registry/main.py"
    click UI "https://github.com/aarora79/mcp-gateway/blob/main/registry/templates/index.html"
    click UI "https://github.com/aarora79/mcp-gateway/blob/main/registry/templates/edit_server.html"
    click UI "https://github.com/aarora79/mcp-gateway/blob/main/registry/templates/login.html"
    click Static "https://github.com/aarora79/mcp-gateway/blob/main/registry/static/style.css"
    click ConfigGen "https://github.com/aarora79/mcp-gateway/blob/main/registry/nginx_template.conf"
    click Nginx "https://github.com/aarora79/mcp-gateway/blob/main/registry/nginx_mcp_revproxy.conf"
    click StateStore "https://github.com/aarora79/mcp-gateway/blob/main/registry/servers/server_state.json"
    click CT "https://github.com/aarora79/mcp-gateway/blob/main/servers/currenttime/server.py"
    click CT "https://github.com/aarora79/mcp-gateway/blob/main/servers/currenttime/client.py"
    click FI "https://github.com/aarora79/mcp-gateway/blob/main/servers/fininfo/server.py"
    click FI "https://github.com/aarora79/mcp-gateway/blob/main/servers/fininfo/client.py"
    click MG "https://github.com/aarora79/mcp-gateway/blob/main/servers/mcpgw/server.py"
    click MG "https://github.com/aarora79/mcp-gateway/blob/main/servers/mcpgw/client.py"
    click RS "https://github.com/aarora79/mcp-gateway/blob/main/servers/realserverfaketools/server.py"
    click RS "https://github.com/aarora79/mcp-gateway/blob/main/servers/realserverfaketools/client.py"
    click StateStore "https://github.com/aarora79/mcp-gateway/blob/main/registry/servers/currenttime.json"
    click StateStore "https://github.com/aarora79/mcp-gateway/blob/main/registry/servers/fininfo.json"
    click StateStore "https://github.com/aarora79/mcp-gateway/blob/main/registry/servers/mcpgw.json"
    click StateStore "https://github.com/aarora79/mcp-gateway/blob/main/registry/servers/realserverfaketools.json"
    click StateStore "https://github.com/aarora79/mcp-gateway/blob/main/registry/servers/server_state.json"
    click EKS "https://github.com/aarora79/mcp-gateway/blob/main/.github/workflows/lint.yml"
    click EKS "https://github.com/aarora79/mcp-gateway/blob/main/build_and_push.sh"

    %% Styles
    classDef agent fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef gateway fill:#90EE90,stroke:#333,stroke-width:1px
    classDef registry fill:#98FB98,stroke:#333,stroke-width:1px
    classDef server fill:#FFA500,stroke:#333,stroke-width:1px
    classDef cloud fill:#DA70D6,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef datastore fill:#B0E0E6,stroke:#333,stroke-width:1px
```
