# aws-samples/sample-bedrock-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/aws-samples/sample-bedrock-mcp
- Repository: https://github.com/aws-samples/sample-bedrock-mcp

## Overview

To accurately capture the architecture of this “Amazon Bedrock + Chainlit + MCP” sample, follow these steps:

##### Project Type and Purpose
- This is a full-stack AI‐powered chat application that:
- Hosts a Chainlit web interface for user interaction
- Uses a ReAct agent (via LangGraph + LangChain) to orchestrate reasoning and tool calls
- Connects to Amazon Bedrock (Anthropic Claude) for LLM capabilities
- Runs a custom MCP server (math operations) as an external tool

##### Main Components
a. Frontend / Web UI
– Chainlit server process (src/ui/app.py)
– Delivers chat UI, handles user input and streaming responses
b. ReAct Agent Layer
– LangGraph agent built with `create_react_agent()`
– LangChain MCP adapters (`load_mcp_tools()`)
c. LLM Service
– AWS Bedrock Anthropic Claude 3.7 Sonnet (via src/utils/bedrock.py)
d. Math MCP Server
– Python wheel built from src/mcp/server.py
– Exposes stdio protocol for add, subtract, multiply, divide
e. Utility Modules
– src/utils/models.py (data models)
– Streaming and AWS credential management

##### Relationships and Data Flow
1) User → Chainlit UI (HTTP/WebSocket)
2) UI → ReAct agent → decision point:
- If no tool needed → call Bedrock API → return text
- If math needed → invoke MCP tool (subprocess stdio) → tool returns result
3) Agent aggregates results → streams back to UI
4) UI renders response in the browser

##### Architectural Patterns
- Microservices: separate UI service and MCP tool service
- Adapter pattern: LangChain MCP adapter bridges MCP stdio to LangChain tools
- ReAct agent pattern: interleaves reasoning (LLM) and acting (tool calls)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["User"]:::external
    User -->|"HTTP/WebSocket"| UI

    %% Frontend UI Layer
    subgraph "Frontend UI" 
        direction TB
        UI["Chainlit UI Server"]:::inprocess
    end

    UI -->|"invoke Agent"| Agent

    %% Agent Layer
    subgraph "ReAct Agent Layer"
        direction TB
        Agent["ReAct Agent\n(LangGraph + LangChain + MCP Adapter)"]:::inprocess
    end

    Agent -->|"REST API"| Bedrock
    Agent -->|"stdio"| MCP

    %% Utility & Services
    subgraph "Utilities & Services"
        direction TB
        Bedrock["Amazon Bedrock\n(Claude 3.7)"]:::cloud
        Models["Data Models"]:::utility
    end

    %% External Tool
    subgraph "External Tools"
        direction TB
        MCP["MCP Math Server\n(stdio)"]:::externaltool
    end

    Bedrock -->|"response"| Agent
    MCP -->|"result"| Agent
    Agent -->|"stream response"| UI
    UI -->|"stream to user"| User

    %% Click Events
    click UI "https://github.com/aws-samples/sample-bedrock-mcp/blob/main/src/ui/app.py"
    click Agent "https://github.com/aws-samples/sample-bedrock-mcp/blob/main/src/ui/app.py"
    click Bedrock "https://github.com/aws-samples/sample-bedrock-mcp/blob/main/src/utils/bedrock.py"
    click MCP "https://github.com/aws-samples/sample-bedrock-mcp/blob/main/src/mcp/server.py"
    click Models "https://github.com/aws-samples/sample-bedrock-mcp/blob/main/src/utils/models.py"

    %% Styles
    classDef inprocess fill:#D0E6FF,stroke:#026AA7,stroke-width:2px
    classDef cloud fill:#DFF7E0,stroke:#2E7D32,stroke-width:2px
    classDef externaltool fill:#FFE6CC,stroke:#E65100,stroke-width:2px
    classDef utility fill:#F0F0F0,stroke:#616161,stroke-width:2px
    classDef external fill:#FFFFFF,stroke:#000000,stroke-width:1px,stroke-dasharray: 5 5
```
