# pietrozullo/mcp-use architecture

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

- Interactive diagram: https://gitdiagram.com/pietrozullo/mcp-use
- Repository: https://github.com/pietrozullo/mcp-use

## Overview

##### Project type and purpose
- This is an open‑source Python library (“mcp_use”) that lets developers connect any LangChain‑compatible LLM to one or more MCP (Model‑Control‑Program) servers.
- It provides core classes for configuring servers, managing sessions, sending LLM tool calls, and processing server responses.

##### File structure
- Top‑level:
- mcp_use/ (core package)
– adapters/ (LangChain adapter)
– agents/ (MCPAgent logic, prompts, server manager)
– connectors/ (HTTP, stdio, WebSocket abstractions)
– task_managers/ (SSE, stdio, WS streaming handlers)
– client.py, config.py, session.py, logging.py
- examples/ (usage scripts & JSON configs)
- docs/ (MDX docs & snippets)
- tests/ (unit tests for each module)
- Key indicators: abstraction layers (connectors & task managers), the agent vs client separation, config via dict or file.

##### README for additional insights
- Describes core concepts: MCPClient, MCPAgent, multi‑server support, dynamic server selection, tool restrictions, debug/logging.
- Shows use cases: web browsing, Airbnb, Blender, HTTP connector, LangChain adapter.

a. Main components
1. External LLMs (e.g., OpenAI, Anthropic via LangChain)
2. MCPAgent (or custom agent via LangChainAdapter)
3. MCPClient
4. MCPSession instances (one per configured server)
5. Connectors (stdio, HTTP, WebSocket)
6. TaskManagers (SSE, stdio, WebSocket)
7. External MCP servers (Playwright, Airbnb, Blender, etc.)
8. Configuration source (dict, JSON file, env)
9. Logging/Debug component
b. Relationships & interactions
- Developer code → loads config → MCPClient.from_dict()/from_config_file
- MCPClient → spawns MCPSession objects per server config
- Each MCPSession → uses Connector to launch or connect to an MCP server
- TaskManager handles streaming events from the Connector
- MCPAgent receives user prompt → calls LLM → receives function/tool call → invokes MCPClient.send_request(server_name, tool_call)
- MCPClient routes to the appropriate MCPSession → Connector → MCP server → TaskManager → returns tool output
- MCPAgent aggregates outputs, invokes LLM for next step until completion
c. Architectural patterns & principles
- Layered modularity (separate adapters, connectors, task managers)
- Dependency inversion (abstract base classes for connectors & task managers)
- Single responsibility (each module handles one concern)
- Extensibility points (new adapters, connectors, servers)
d. Key technologies & libraries
- Python 3.11+, asyncio
- subprocess (stdio connector), aiohttp or httpx (HTTP connector), websockets
- SSE streaming
- LangChain for LLM integration
- Dotenv for env config
- JSON config files

##### Detailed component breakdown (recommend including these
- Configuration Loader (from dict or JSON)
- MCPClient
- manages MCPSession pool
- exposes send_request(), close_all_sessions()
- MCPSession
- Connector (stdio / HTTP / WebSocket)
- TaskManager (SSE / stdio / WebSocket)
- MCPAgent
- llm: external LangChain model
- tool loop: get next action, call client, parse result
- optional ServerManager for dynamic selection
- Adapters (e.g., LangChainAdapter.create_tools())
- Logging & Debug (global flags, agent.verbose)
- Example scripts (browser_use.py, airbnb_use.py, blender_use.py)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Configuration and Examples
    subgraph "Configuration & Examples"
        direction TB
        ConfigSource["Config Source\n(dict/JSON/env)"]:::config
        Examples["Example Scripts\n& JSON Configs"]:::config
    end

    %% Core Library Modules
    subgraph "Core Library" 
        direction TB
        ConfigLoader["Configuration Loader"]:::internal
        MCPClient["MCPClient"]:::internal
        MCPSession["MCPSession"]:::internal

        subgraph "Connectors"
            direction TB
            BaseConnector["BaseConnector"]:::internal
            HTTPConnector["HTTP Connector"]:::internal
            StdioConnector["Stdio Connector"]:::internal
            WebSocketConnector["WebSocket Connector"]:::internal
        end

        subgraph "TaskManagers"
            direction TB
            BaseTaskManager["BaseTaskManager"]:::internal
            SseTaskManager["SSE TaskManager"]:::internal
            StdioTaskManager["Stdio TaskManager"]:::internal
            WsTaskManager["WebSocket TaskManager"]:::internal
        end

        subgraph "Agents"
            direction TB
            MCPAgent["MCPAgent"]:::internal
            BaseAgent["BaseAgent"]:::internal
            ServerManager["ServerManager"]:::internal
            SystemPromptBuilder["SystemPromptBuilder"]:::internal
            PromptTemplates["PromptTemplates"]:::internal
        end

        subgraph "Adapters"
            direction TB
            BaseAdapter["BaseAdapter"]:::internal
            LangChainAdapter["LangChainAdapter"]:::internal
        end

        Logging["Logging & Debug"]:::internal
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        LLMProvider["External LLM Providers"]:::external
        MCPServers["MCP Servers\n(Playwright, Airbnb, etc.)"]:::external
    end

    %% Flow definitions
    ConfigSource -->|loads config| ConfigLoader
    Examples -->|provide configs| ConfigLoader
    ConfigLoader -->|init| MCPClient
    MCPClient -->|spawn sessions| MCPSession

    MCPSession -->|uses| BaseConnector
    BaseConnector --> HTTPConnector
    BaseConnector --> StdioConnector
    BaseConnector --> WebSocketConnector

    MCPSession -->|uses| BaseTaskManager
    BaseTaskManager --> SseTaskManager
    BaseTaskManager --> StdioTaskManager
    BaseTaskManager --> WsTaskManager

    MCPAgent -->|calls LLM| LLMProvider
    LLMProvider -->|returns response| MCPAgent

    MCPAgent -->|send_request| MCPClient
    MCPClient -->|route to| MCPSession
    MCPSession -->|connect via| HTTPConnector
    MCPSession -->|connect via| StdioConnector
    MCPSession -->|connect via| WebSocketConnector
    HTTPConnector -->|to| MCPServers
    StdioConnector -->|to| MCPServers
    WebSocketConnector -->|to| MCPServers

    MCPServers -->|streams| SseTaskManager
    MCPServers -->|streams| StdioTaskManager
    MCPServers -->|streams| WsTaskManager

    SseTaskManager -->|returns data| MCPClient
    StdioTaskManager -->|returns data| MCPClient
    WsTaskManager -->|returns data| MCPClient

    MCPClient -->|response| MCPAgent
    MCPAgent -->|output| Examples

    %% Adapters and Utilities
    LangChainAdapter -.->|plugin point| MCPAgent
    BaseAdapter -.->|extend| LangChainAdapter

    Logging -.-> MCPClient
    Logging -.-> MCPAgent

    %% Click events
    click ConfigLoader "https://github.com/pietrozullo/mcp-use/blob/main/mcp_use/config.py"
    click MCPClient "https://github.com/pietrozullo/mcp-use/blob/main/mcp_use/client.py"
    click MCPSession "https://github.com/pietrozullo/mcp-use/blob/main/mcp_use/session.py"
    click BaseConnector "https://github.com/pietrozullo/mcp-use/blob/main/mcp_use/connectors/base.py"
    click HTTPConnector "https://github.com/pietrozullo/mcp-use/blob/main/mcp_use/connectors/http.py"
    click StdioConnector "https://github.com/pietrozullo/mcp-use/blob/main/mcp_use/connectors/stdio.py"
    click WebSocketConnector "https://github.com/pietrozullo/mcp-use/blob/main/mcp_use/connectors/websocket.py"
    click BaseTaskManager "https://github.com/pietrozullo/mcp-use/blob/main/mcp_use/task_managers/base.py"
    click SseTaskManager "https://github.com/pietrozullo/mcp-use/blob/main/mcp_use/task_managers/sse.py"
    click StdioTaskManager "https://github.com/pietrozullo/mcp-use/blob/main/mcp_use/task_managers/stdio.py"
    click WsTaskManager "https://github.com/pietrozullo/mcp-use/blob/main/mcp_use/task_managers/websocket.py"
    click MCPAgent "https://github.com/pietrozullo/mcp-use/blob/main/mcp_use/agents/mcpagent.py"
    click BaseAgent "https://github.com/pietrozullo/mcp-use/blob/main/mcp_use/agents/base.py"
    click ServerManager "https://github.com/pietrozullo/mcp-use/blob/main/mcp_use/agents/server_manager.py"
    click SystemPromptBuilder "https://github.com/pietrozullo/mcp-use/blob/main/mcp_use/agents/prompts/system_prompt_builder.py"
    click PromptTemplates "https://github.com/pietrozullo/mcp-use/blob/main/mcp_use/agents/prompts/templates.py"
    click BaseAdapter "https://github.com/pietrozullo/mcp-use/blob/main/mcp_use/adapters/base.py"
    click LangChainAdapter "https://github.com/pietrozullo/mcp-use/blob/main/mcp_use/adapters/langchain_adapter.py"
    click Logging "https://github.com/pietrozullo/mcp-use/blob/main/mcp_use/logging.py"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef external fill:#98FB98,stroke:#000,stroke-width:1px
    classDef config fill:#FFA500,stroke:#000,stroke-width:1px
    class ConfigSource,Examples config
    class LLMProvider,MCPServers external
```
