# dorenatwork/mcp-guardian architecture

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

- Interactive diagram: https://gitdiagram.com/dorenatwork/mcp-guardian
- Repository: https://github.com/dorenatwork/mcp-guardian

## Overview

MCP Guardian is an initial FastAPI scaffold for an enterprise MCP control-plane gateway. The demonstrated workflow accepts a client POST, checks the HTTP envelope and body size, validates JSON-RPC metadata and protocol version, and returns discovery data or a protocol-safe error; it explicitly does not execute upstream requests. The router also composes named control-plane API areas and health routes, but their implementations are not shown. The graph reflects that limit: those areas are represented as scaffold capabilities, not asserted runtime workflows.

Main entry points: [`apps/gateway/mcp_request/service.py`](https://github.com/dorenatwork/mcp-guardian/blob/main/apps/gateway/mcp_request/service.py) (MCP protocol service), [`apps/gateway/mcp_request/views/post/handle.py`](https://github.com/dorenatwork/mcp-guardian/blob/main/apps/gateway/mcp_request/views/post/handle.py) (MCP POST handler), [`apps/urls.py`](https://github.com/dorenatwork/mcp-guardian/blob/main/apps/urls.py) (API router), [`infrastructure/mcp/decoder.py`](https://github.com/dorenatwork/mcp-guardian/blob/main/infrastructure/mcp/decoder.py) (JSON-RPC decoder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application and routing"]
  node_app["FastAPI application<br/>[main.py]"]
  node_api_router["API router<br/>[urls.py]"]
end

subgraph group_gateway["MCP request boundary"]
  node_gateway_routes["Gateway routes<br/>[urls.py]"]
  node_mcp_handler["MCP POST handler<br/>[handle.py]"]
  node_mcp_service["MCP protocol service<br/>[service.py]"]
  node_request_params["Discovery parameters<br/>[requests.py]"]
  node_response_models["MCP response models<br/>[responses.py]"]
end

subgraph group_protocol["Protocol validation"]
  node_http_transport["HTTP envelope checks<br/>[http_transport.py]"]
  node_decoder["JSON-RPC decoder<br/>[decoder.py]"]
  node_header_validation["Mirrored header checks"]
  node_protocol_models["Protocol message models<br/>[models.py]"]
  node_protocol_errors["Protocol errors<br/>[errors.py]"]
end

subgraph group_platform["Shared platform"]
  node_settings["Runtime settings<br/>[settings.py]"]
end

subgraph group_capabilities["Control-plane capabilities"]
  node_monitoring_routes["Health routes<br/>[urls.py]"]
  node_health_views["Health endpoints"]
  node_health_service["Health status service<br/>[service.py]"]
  node_other_api_areas["Other control APIs"]
  node_data_layer[("Models and repositories")]
  node_integrations["Provider adapters"]
end

node_client(("MCP client"))

node_client -->|"POSTs request"| node_mcp_handler
node_app -->|"mounts routes"| node_api_router
node_api_router -->|"includes router"| node_gateway_routes
node_api_router -->|"includes router"| node_monitoring_routes
node_api_router -->|"includes routers"| node_other_api_areas
node_gateway_routes -->|"routes to"| node_mcp_handler
node_mcp_handler -->|"calls"| node_mcp_service
node_mcp_handler -->|"reads bounded body"| node_http_transport
node_mcp_handler -->|"serializes errors"| node_response_models
node_mcp_service -->|"validates envelope"| node_http_transport
node_mcp_service -->|"decodes message"| node_decoder
node_mcp_service -->|"checks metadata"| node_header_validation
node_mcp_service -->|"validates discovery"| node_request_params
node_mcp_service -->|"builds discovery"| node_response_models
node_mcp_service -->|"reads configuration"| node_settings
node_decoder -->|"creates messages"| node_protocol_models
node_decoder -->|"raises errors"| node_protocol_errors
node_http_transport -->|"raises errors"| node_protocol_errors
node_monitoring_routes -->|"routes to"| node_health_views
node_health_views -.->|"uses status service"| node_health_service

click node_app "https://github.com/dorenatwork/mcp-guardian/blob/main/main.py"
click node_api_router "https://github.com/dorenatwork/mcp-guardian/blob/main/apps/urls.py"
click node_gateway_routes "https://github.com/dorenatwork/mcp-guardian/blob/main/apps/gateway/urls.py"
click node_mcp_handler "https://github.com/dorenatwork/mcp-guardian/blob/main/apps/gateway/mcp_request/views/post/handle.py"
click node_mcp_service "https://github.com/dorenatwork/mcp-guardian/blob/main/apps/gateway/mcp_request/service.py"
click node_request_params "https://github.com/dorenatwork/mcp-guardian/blob/main/apps/gateway/mcp_request/serializers/requests.py"
click node_response_models "https://github.com/dorenatwork/mcp-guardian/blob/main/apps/gateway/mcp_request/serializers/responses.py"
click node_http_transport "https://github.com/dorenatwork/mcp-guardian/blob/main/infrastructure/mcp/http_transport.py"
click node_decoder "https://github.com/dorenatwork/mcp-guardian/blob/main/infrastructure/mcp/decoder.py"
click node_header_validation "https://github.com/dorenatwork/mcp-guardian/blob/main/infrastructure/mcp/header_validation.py"
click node_protocol_models "https://github.com/dorenatwork/mcp-guardian/blob/main/infrastructure/mcp/models.py"
click node_protocol_errors "https://github.com/dorenatwork/mcp-guardian/blob/main/infrastructure/mcp/errors.py"
click node_settings "https://github.com/dorenatwork/mcp-guardian/blob/main/shared/config/settings.py"
click node_monitoring_routes "https://github.com/dorenatwork/mcp-guardian/blob/main/apps/monitoring/urls.py"
click node_health_views "https://github.com/dorenatwork/mcp-guardian/tree/main/apps/monitoring/system_health/views"
click node_health_service "https://github.com/dorenatwork/mcp-guardian/blob/main/apps/monitoring/system_health/service.py"
click node_other_api_areas "https://github.com/dorenatwork/mcp-guardian/tree/main/apps"
click node_data_layer "https://github.com/dorenatwork/mcp-guardian/tree/main/data"
click node_integrations "https://github.com/dorenatwork/mcp-guardian/tree/main/infrastructure"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_api_router,node_client toneBlue
class node_gateway_routes,node_mcp_handler,node_mcp_service,node_request_params,node_response_models toneAmber
class node_http_transport,node_decoder,node_header_validation,node_protocol_models,node_protocol_errors toneMint
class node_settings toneRose
class node_monitoring_routes,node_health_views,node_health_service,node_other_api_areas,node_data_layer,node_integrations toneIndigo
```

## Components

### Application and routing

- [FastAPI application](https://github.com/dorenatwork/mcp-guardian/blob/main/main.py): `main.py`
- [API router](https://github.com/dorenatwork/mcp-guardian/blob/main/apps/urls.py): `apps/urls.py`

### MCP request boundary

- [Gateway routes](https://github.com/dorenatwork/mcp-guardian/blob/main/apps/gateway/urls.py): `apps/gateway/urls.py`
- [MCP POST handler](https://github.com/dorenatwork/mcp-guardian/blob/main/apps/gateway/mcp_request/views/post/handle.py): `apps/gateway/mcp_request/views/post/handle.py`
- [MCP protocol service](https://github.com/dorenatwork/mcp-guardian/blob/main/apps/gateway/mcp_request/service.py): `apps/gateway/mcp_request/service.py`
- [Discovery parameters](https://github.com/dorenatwork/mcp-guardian/blob/main/apps/gateway/mcp_request/serializers/requests.py): `apps/gateway/mcp_request/serializers/requests.py`
- [MCP response models](https://github.com/dorenatwork/mcp-guardian/blob/main/apps/gateway/mcp_request/serializers/responses.py): `apps/gateway/mcp_request/serializers/responses.py`

### Protocol validation

- [HTTP envelope checks](https://github.com/dorenatwork/mcp-guardian/blob/main/infrastructure/mcp/http_transport.py): `infrastructure/mcp/http_transport.py`
- [JSON-RPC decoder](https://github.com/dorenatwork/mcp-guardian/blob/main/infrastructure/mcp/decoder.py): `infrastructure/mcp/decoder.py`
- [Mirrored header checks](https://github.com/dorenatwork/mcp-guardian/blob/main/infrastructure/mcp/header_validation.py): `infrastructure/mcp/header_validation.py`
- [Protocol message models](https://github.com/dorenatwork/mcp-guardian/blob/main/infrastructure/mcp/models.py): `infrastructure/mcp/models.py`
- [Protocol errors](https://github.com/dorenatwork/mcp-guardian/blob/main/infrastructure/mcp/errors.py): `infrastructure/mcp/errors.py`

### Shared platform

- [Runtime settings](https://github.com/dorenatwork/mcp-guardian/blob/main/shared/config/settings.py): `shared/config/settings.py`

### Control-plane capabilities

- [Health routes](https://github.com/dorenatwork/mcp-guardian/blob/main/apps/monitoring/urls.py): `apps/monitoring/urls.py`
- [Health endpoints](https://github.com/dorenatwork/mcp-guardian/tree/main/apps/monitoring/system_health/views): `apps/monitoring/system_health/views`
- [Health status service](https://github.com/dorenatwork/mcp-guardian/blob/main/apps/monitoring/system_health/service.py): `apps/monitoring/system_health/service.py`
- [Other control APIs](https://github.com/dorenatwork/mcp-guardian/tree/main/apps): `apps`
- [Models and repositories](https://github.com/dorenatwork/mcp-guardian/tree/main/data): `data`
- [Provider adapters](https://github.com/dorenatwork/mcp-guardian/tree/main/infrastructure): `infrastructure`

### Other components

- **MCP client**

## Connections

- MCP client → MCP POST handler: POSTs request (evidence: `apps/gateway/mcp_request/views/post/handle.py`)
- FastAPI application → API router: mounts routes (evidence: `main.py`)
- API router → Gateway routes: includes router (evidence: `apps/urls.py`)
- API router → Health routes: includes router (evidence: `apps/urls.py`)
- API router → Other control APIs: includes routers (evidence: `apps/urls.py`)
- Gateway routes → MCP POST handler: routes to (evidence: `apps/gateway/urls.py`)
- MCP POST handler → MCP protocol service: calls (evidence: `apps/gateway/mcp_request/views/post/handle.py`)
- MCP POST handler → HTTP envelope checks: reads bounded body (evidence: `apps/gateway/mcp_request/views/post/handle.py`)
- MCP POST handler → MCP response models: serializes errors (evidence: `apps/gateway/mcp_request/views/post/handle.py`)
- MCP protocol service → HTTP envelope checks: validates envelope (evidence: `apps/gateway/mcp_request/service.py`)
- MCP protocol service → JSON-RPC decoder: decodes message (evidence: `apps/gateway/mcp_request/service.py`)
- MCP protocol service → Mirrored header checks: checks metadata (evidence: `apps/gateway/mcp_request/service.py`)
- MCP protocol service → Discovery parameters: validates discovery (evidence: `apps/gateway/mcp_request/service.py`)
- MCP protocol service → MCP response models: builds discovery (evidence: `apps/gateway/mcp_request/service.py`)
- MCP protocol service → Runtime settings: reads configuration (evidence: `apps/gateway/mcp_request/service.py`)
- JSON-RPC decoder → Protocol message models: creates messages (evidence: `infrastructure/mcp/decoder.py`)
- JSON-RPC decoder → Protocol errors: raises errors (evidence: `infrastructure/mcp/decoder.py`)
- HTTP envelope checks → Protocol errors: raises errors (evidence: `infrastructure/mcp/http_transport.py`)
- Health routes → Health endpoints: routes to (evidence: `apps/monitoring/urls.py`)
- Health endpoints → Health status service: uses status service