# aws-samples/demo_mcp_on_amazon_bedrock architecture

> Architecture diagram of the GitHub repository aws-samples/demo_mcp_on_amazon_bedrock, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws-samples/demo_mcp_on_amazon_bedrock
- Repository: https://github.com/aws-samples/demo_mcp_on_amazon_bedrock

## Overview

##### Main Components
- Backend Service(s):
- The core backend is written in Python (files like main.py, mcp_client.py, chat_client.py, chat_client_stream.py) and uses FastAPI to expose REST APIs for chatting and MCP management.
- It handles user sessions, chat processing, and coordinates calls to Amazon Bedrock services and the MCP servers.
- MCP Client:
- This module (e.g., mcp_client.py) manages the connections with multiple external MCP servers. It enables the backend to delegate specialized tasks (e.g., file system operations, web search, browser control) in a decoupled way.
- Frontend Interfaces:
- A Streamlit-based Web UI (chatbot.py) that offers a simple interface for end users who want to interact with the chat system.
- A modern React UI (in the react_ui folder, built with Next.js, Tailwind CSS, and Shadcn UI) providing a more dynamic, multi-user experience with session management, theming, and real-time streaming responses.
- AWS/CDK Infrastructure:
- The cdk directory shows infrastructure-as-code setups for deploying parts of this system on AWS, ensuring that the environment (using services like Bedrock) is provisioned correctly.
- External Services / MCP Servers:
- The project integrates with various external MCP servers which may include Node.js or Python based implementations. The configuration (in conf/config.json) details the commands, arguments, and environment settings for each MCP server. These servers add functionality (like browser automation, external search, even remote desktop control via EC2) to the ChatBot.

##### Relationships and Interactions
- The Frontend (whether via Streamlit or React UI) communicates via REST APIs (hosted by the FastAPI backend service) with the backend.
- The backend receives and processes chat requests, interacting with Amazon Bedrock for primary model responses.
- When the model response requires tool calls, the MCP client initiates and manages calls to the configured MCP servers. These calls are often done dynamically based on the user’s request or the model’s “thinking” process.
- The CDK components define parts of the deployment (e.g., VPCs, server settings) for hosting this system on AWS.
- All interactions and data flows should show clear directional flows—for instance, user → Frontend → API Gateway/Backend → Amazon Bedrock, with branch-outs toward MCP Servers.

##### Architectural Patterns and Design Principles
- Frontend-backend separation: Clear REST API boundaries.
- Modular design: The use of distinct modules (chat client, MCP client, main service) lends itself to a microservices/micro-module approach.
- Extensibility: The project is designed so that additional MCP servers can be plugged in easily (see configuration files and UI functionality).
- Scalable infrastructure: The use of Next.js for the React UI and AWS CDK for managing cloud resources demonstrate attention to scalability and continuous deployment.

##### Relevant Technologies
- Backend: Python, FastAPI, uv (Python package manager), and command-line based MCP launching.
- Frontend: Streamlit for a simple UI; React with Next.js, Tailwind CSS, and Shadcn UI components for a modern, responsive UI.
- Cloud Deployment: AWS services along with CDK (in the cdk folder) for provisioning.
- External Integration: Amazon Bedrock (Nova/Claude models), various MCP servers written in Node.js or Python, and additional external tools/libraries.

##### Elements
- From user → Frontend → Backend → Amazon Bedrock
- From backend → MCP Client → External MCP Servers and back.
- UI components (perhaps rounded rectangles)
- Backend services (standard rectangles)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    User["User"]:::user

    %% Frontend Subgraph
    subgraph "Frontend Layer"
        StreamlitUI["Streamlit ChatBot UI"]:::frontend
        ReactUI["React UI - Next.js"]:::frontend
    end

    %% Backend Subgraph
    subgraph "FastAPI Backend"
        Backend["FastAPI Backend"]:::backend
        subgraph "Backend Modules"
            ChatClient["Chat Client Module"]:::backendModule
            ChatClientStream["Chat Client Stream Module"]:::backendModule
            MCPClient["MCP Client Module"]:::backendModule
        end
    end

    %% External Services and Infrastructure
    Bedrock["Amazon Bedrock Service"]:::external
    MCPServers["External MCP Servers"]:::external
    CDK["AWS/CDK Infrastructure"]:::infrastructure

    %% Data Flow Arrows
    User -->|"initiates"| StreamlitUI
    User -->|"initiates"| ReactUI
    StreamlitUI -->|"calls API"| Backend
    ReactUI -->|"calls API"| Backend
    Backend -->|"processes chat"| ChatClient
    Backend -->|"processes streaming chat"| ChatClientStream
    ChatClient -->|"gets response"| Bedrock
    ChatClientStream -->|"gets response"| Bedrock
    Backend -->|"delegates tool calls"| MCPClient
    MCPClient -->|"invokes"| MCPServers
    MCPServers -->|"returns results"| MCPClient
    CDK -->|"deploys"| Backend

    %% Click Events
    click Backend "https://github.com/aws-samples/demo_mcp_on_amazon_bedrock/blob/main/src/main.py"
    click ChatClient "https://github.com/aws-samples/demo_mcp_on_amazon_bedrock/blob/main/src/chat_client.py"
    click ChatClientStream "https://github.com/aws-samples/demo_mcp_on_amazon_bedrock/blob/main/src/chat_client_stream.py"
    click MCPClient "https://github.com/aws-samples/demo_mcp_on_amazon_bedrock/blob/main/src/mcp_client.py"
    click StreamlitUI "https://github.com/aws-samples/demo_mcp_on_amazon_bedrock/blob/main/chatbot.py"
    click ReactUI "https://github.com/aws-samples/demo_mcp_on_amazon_bedrock/tree/main/react_ui/"
    click CDK "https://github.com/aws-samples/demo_mcp_on_amazon_bedrock/tree/main/cdk/"
    click MCPServers "https://github.com/aws-samples/demo_mcp_on_amazon_bedrock/blob/main/conf/config.json"

    %% Styles
    classDef user fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef frontend fill:#B3E5FC,stroke:#0277BD,stroke-width:2px,stroke-dasharray: 5 5,rx:5,ry:5;
    classDef backend fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef backendModule fill:#E8F5E9,stroke:#388E3C,stroke-width:1px;
    classDef external fill:#FFCDD2,stroke:#C62828,stroke-width:2px,stroke-dasharray: 3 3,rx:5,ry:5;
    classDef infrastructure fill:#D1C4E9,stroke:#512DA8,stroke-width:2px,stroke-dasharray: 2 2,rx:5,ry:5;
```
