# teddynote-lab/langgraph-mcp-agents architecture

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

- Interactive diagram: https://gitdiagram.com/teddynote-lab/langgraph-mcp-agents
- Repository: https://github.com/teddynote-lab/langgraph-mcp-agents

## Overview

##### Project Type and Purpose
- This is a full-stack application that provides a Streamlit-based user interface for managing and interacting with MCP (Model Context Protocol) tools for LangGraph agents.
- The project enables AI agents to access external tools and data sources through MCP, specifically integrating LangChain’s ReAct agent paradigm with MCP functionalities.
- The README clarifies that the aim is to support tool management, streaming responses, conversation tracking, and flexible integration with multiple MCP servers (local, remote, and RAG).

##### File Structure
- Top-level files include environment examples (.env.example), configuration files (pyproject.toml, requirements.txt, uv.lock), and language-specific implementations (app.py for English and app_KOR.py for Korean). This indicates multilingual support in the UI.
- Files like mcp_server_local.py, mcp_server_rag.py, and mcp_server_remote.py represent the different MCP server modes or integration points. They encapsulate the server-side logic required for accessing external tools.
- Jupyter notebooks (MCP-HandsOn-ENG.ipynb and MCP-HandsOn-KOR.ipynb) offer hands-on tutorials demonstrating how to set up and integrate MCP on various transports (SSE, Stdio, etc.) with LangGraph.

##### Key Components
- Frontend (Streamlit UI): Represented by app.py / app_KOR.py, this is the user interface that allows users to manage tools (using Smithery JSON configurations), view responses, and interact with the agent.
- MCP Client: The component that manages a 1:1 connection between the UI or host and the MCP server. The hands-on notebooks explain the client’s configuration and usage.
- Local MCP Server (mcp_server_local.py)
- RAG Integration MCP Server (mcp_server_rag.py)
- Remote MCP Server (mcp_server_remote.py)
- External Services & Data Sources: Illustrate external tools/data sources (such as APIs, LangChain tools, and possibly external MCP hosts like Claude Desktop or IDE integrations) that the MCP servers expose.
- Model Context Protocol (MCP) Architecture Components: Highlight the three MCP roles mentioned in the README:
- MCP Host: Applications that need data access.
- MCP Client: The intermediaries managing direct communication.
- MCP Server: Provides data and functionality through MCP.

##### Relationships and Interactions
- Data flow between MCP Servers and External Data Sources/Tools, emphasizing that these servers fetch and push data as required.
- Dynamic tool management workflow: from entering configurations (JSON strings, via the UI) to the MCP Client initializing new tool connections, updating the agent with newly added tools.

##### Architectural Patterns & Design Principles
- Modular design – where each MCP server implementation is independent, allowing flexibility (e.g., using different transport methods like SSE and Stdio).
- Separation of concerns between the UI (interaction and configuration), the MCP Client (communication & protocol handling), and the MCP Servers (data provision/execution of tool logic).
- The pattern follows a microservices-like approach for the MCP servers while centralizing client handling for the ReAct agent.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Frontend Layer"
        UI_eng["Streamlit UI - English (app.py)"]:::ui
        UI_kor["Streamlit UI - Korean (app_KOR.py)"]:::ui
    end

    subgraph "Client Layer"
        Client["MCP Client"]:::client
    end

    subgraph "Server Layer"
        Server_local["MCP Server – Local"]:::server
        Server_rag["MCP Server – RAG Integration"]:::server
        Server_remote["MCP Server – Remote"]:::server
    end

    subgraph "External Layer"
        External["External Services & Data Sources"]:::external
    end

    UI_eng -->|"sends command"| Client
    UI_kor -->|"sends command"| Client

    Client -->|"connects to"| Server_local
    Client -->|"connects to"| Server_rag
    Client -->|"connects to"| Server_remote

    Server_local -->|"fetches data"| External
    Server_rag -->|"fetches data"| External
    Server_remote -->|"fetches data"| External

    click UI_eng "https://github.com/teddynote-lab/langgraph-mcp-agents/blob/master/app.py"
    click UI_kor "https://github.com/teddynote-lab/langgraph-mcp-agents/blob/master/app_KOR.py"
    click Server_local "https://github.com/teddynote-lab/langgraph-mcp-agents/blob/master/mcp_server_local.py"
    click Server_rag "https://github.com/teddynote-lab/langgraph-mcp-agents/blob/master/mcp_server_rag.py"
    click Server_remote "https://github.com/teddynote-lab/langgraph-mcp-agents/blob/master/mcp_server_remote.py"
    click Client "https://github.com/teddynote-lab/langgraph-mcp-agents/blob/master/MCP-HandsOn-ENG.ipynb"
    click Client "https://github.com/teddynote-lab/langgraph-mcp-agents/blob/master/MCP-HandsOn-KOR.ipynb"
    click External "https://github.com/teddynote-lab/langgraph-mcp-agents/tree/master/assets"

    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef client fill:#87CEFA,stroke:#000,stroke-width:2px;
    classDef server fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
