Architectural diagrams
This page contains architectural diagrams as specified by the C4 model.
The C4 model is a framework for visualizing the architecture of software systems in a clear and structured way. It provides a hierarchical set of diagrams that describe a system at multiple levels of abstraction, making it easier for both technical and non-technical stakeholders to understand. The model focuses on four levels:
- Context Diagram – Shows the system’s interactions with users, external systems, and the environment.
- Container Diagram – Breaks the system into containers (applications, services, databases), highlighting responsibilities and technology choices.
- Component Diagram – Details the internal components of each container and how they collaborate.
- Code (or Class) Diagram – Provides a detailed view of the implementation, showing classes, interfaces, and relationships.
It also supports dynamic (communication) diagrams to illustrate how elements interact at runtime, helping teams understand both structure and behavior clearly.
For this project, the following diagrams are provided in this page:
- three system context diagrams
- seven container diagrams
- one container diagram of the MCP server
- two container diagrams of Claude Desktop, one for open access to the MCP server and one for restricted access to the MCP server
- four container diagrams of the MCP Inspector, two for Direct mode (open and restricted access), and two for Proxy mode (open and restricted access)
- one component diagram
- three dynamic diagrams
- one describing how the AI application gets an access token for the MCP server with restricted access by means of OAuth Authorization Code Flow
- one describing how the MCP server gets an access token for the Downstream API system with restricted access by means of OAuth Token Exchange
- one describing how the Downstream User gets the response from the AI Application
- one code diagram, describing the module dependencies within the MCP server
The first setup is the simplest one, with no authentication: it can be used when the MCP server is not publicly accessible (for example when it is deployed in the user's pc) and the Downstream API System either doesn't require authentication or an access token has already been issued to the user (refer to BACKEND_API_AUTH and BACKEND_AUTH_TOKEN configuration parameters).
In this setup it is important to configure the MCP Server for DNS Rebinding protection (refer to MCP_SERVER_DNS_REBINDING_PROTECTION_ALLOWED_HOSTS and MCP_SERVER_DNS_REBINDING_PROTECTION_ALLOWED_ORIGINS configuration parameters).
This is a setup with authentication only on the side of the MCP Server. It can be used when the MCP server is publicly accessible (for example when it is deployed in a Cloud) and the Downstream Server doesn't require authentication or an access token has already been issued for it.
In this setup it is important to configure the MCP Server for TLS (TLS_CERT_PATH and TLS_KEY_PATH).
The Container diagram for the MCP server is trivial since the MCP Server system is made just by one container.
