# lastmile-ai/mcp-agent architecture

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

- Interactive diagram: https://gitdiagram.com/lastmile-ai/mcp-agent
- Repository: https://github.com/lastmile-ai/mcp-agent

## Overview

##### Main Components
- Core Framework Module:
- MCPApp (src/mcp_agent/app.py): The global state container and configuration loader.
- Configuration and Logging (src/mcp_agent/config.py and src/mcp_agent/logging/*): These modules manage runtime behavior (loggers, transports, etc.) and connect to the configuration files (mcp_agent.config.yaml).
- Agent System:
- Agent definition and behavior (src/mcp_agent/agents/agent.py): Represents individual agents that expose MCP server functions.
- CLI Module (src/mcp_agent/cli): Command-line interfaces to interact with the agents.
- LLM and Augmentation:
- AugmentedLLM base and its derivatives (src/mcp_agent/workflows/llm/*): These wrap LLM interactions and are enhanced with tool/agent capabilities.
- Workflows Patterns:
- Parallel, Orchestrator, Router, Intent-Classifiers, Evaluator–Optimizer, and Swarm (organized in src/mcp_agent/workflows/…): Each workflow is a composable pattern that wraps around the basic LLM. These should be represented as distinct modules that can be composed with agents.
- MCP Server Connections:
- MCP connection management and aggregation (src/mcp_agent/mcp and src/mcp_agent/mcp_aggregator.py): Manage the connection lifecycle to external MCP servers (like fetch and filesystem) and combine them in a server aggregator.
- Telemetry and Data Modules:
- Various modules for context, event progress, and telemetry, which help monitor execution and debugging.
- Examples and Tests:
- The examples/ directory shows multiple sample applications (e.g., mcp_basic_agent, mcp_agent_server, workflow examples) that demonstrate different use cases and how to integrate the core framework elements.
- Supporting Scripts and Tools:
- Script utilities for events, linting, schema generation, etc. (scripts/ directory)

##### Relationships and Interactions
- From the User’s Perspective:
- The user starts the application via CLI, script, or from an example. The MCPApp is initialized—with configuration and logging set up.
- Agent Composition:
- Agents are instantiated with specific instructions and link to a defined set of MCP servers using configuration (via mcp connection functions and even MCPAggregator).
- An agent attaches an AugmentedLLM that grants it enhanced capabilities for multi-turn conversations and tool calls.
- Workflow Execution:
- Individual workflows (parallel, router, orchestrator, etc.) take inputs from agents/LLM and internally route or coordinate sub-agent calls.
- They use designated agents (sub-agents) to perform steps, and then fan in or aggregate results.
- External Interactions:
- When an agent needs to call external services (like fetching data from a URL, reading files, etc.), it invokes MCP servers. The connection manager (or gen_client) handles the lifecycle of these servers.
- Data Flows:

##### Architectural Patterns & Important Principles
- Composability – each workflow is implemented as an AugmentedLLM, making it easy to chain and nest functionalities.
- Separation of Concerns – configuration, logging, server management, and the core logic of agents and workflows are all modularized.
- Extensibility – new workflows or external server connectors can be added without reworking the entire framework.
- Async Execution – the use of asynchronous programming (note the extensive use of async contexts) is critical to the design.

##### Relevant Technologies and Frameworks
- Python’s asyncio for managing asynchronous tasks.
- YAML-based configuration and secrets (mcp_agent.config.yaml, mcp_agent.secrets.yaml).
- GitHub Actions (in .github/workflows) for CI/CD.
- Third-party libraries like uv (for project management) and integrations with external LLM providers (OpenAI, Anthropic, etc.).

##### Specific Elements
- Initialization flows (configuration → MCPApp).
- Operational flows (Agent → LLM (AugmentedLLM) → Workflow call → external MCP server request → response back to Agent).
- Annotations highlighting architectural patterns (such as “Parallel Workflow”, “Router”, “Orchestrator”) with code examples available in respective directories.
- Internal framework components versus external integrations (e.g., MCP servers).
- User interface components (CLI/terminal) versus background processing elements.
- Data stores or configuration files (like mcp_agent.config.yaml and secrets) as separate configuration blocks feeding into the system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    UserInput["User Input"]:::user
    Examples["Examples"]:::examples
    Scripts["Supporting Scripts"]:::scripts

    %% CLI Layer
    CLIModule["CLI Module"]:::cli

    %% Core Framework Layer
    ConfigLogging["Config & Logging"]:::core
    MCPApp["MCPApp"]:::core
    Agent["Agent"]:::core

    %% Augmented LLM
    AugLLM["AugmentedLLM"]:::llm

    %% Workflows Subgraph
    subgraph "Workflows"
        ParallelWF["Parallel Workflow"]:::workflow
        OrchestratorWF["Orchestrator Workflow"]:::workflow
        RouterWF["Router Workflow"]:::workflow
        EvaluatorOptWF["EvaluatorOptimizer Workflow"]:::workflow
        SwarmWF["Swarm Workflow"]:::workflow
        WorkflowAgg["Workflow Aggregator"]:::workflow
    end

    %% External MCP Server Connections
    MCPServer["MCP Server Connections"]:::mcp

    %% Telemetry and Data
    Telemetry["Telemetry & Data"]:::telemetry

    %% Connections
    UserInput -->|"start_app"| CLIModule
    Examples -->|"demo_call"| CLIModule
    Scripts -->|"script_call"| CLIModule

    CLIModule -->|"init_flow"| ConfigLogging
    ConfigLogging -->|"config_flow"| MCPApp
    MCPApp -->|"create_agent"| Agent
    Agent -->|"attach_llm"| AugLLM

    AugLLM -->|"invoke_workflow"| WorkflowAgg

    %% Individual workflows contribute their results to the aggregator
    ParallelWF -->|"result"| WorkflowAgg
    OrchestratorWF -->|"result"| WorkflowAgg
    RouterWF -->|"result"| WorkflowAgg
    EvaluatorOptWF -->|"result"| WorkflowAgg
    SwarmWF -->|"result"| WorkflowAgg

    WorkflowAgg -->|"result_return"| Agent

    %% Workflow engine interacts with MCP Server Connections
    WorkflowAgg -->|"server_call"| MCPServer
    MCPServer -->|"server_response"| WorkflowAgg

    Agent -->|"logging_flow"| Telemetry
    Agent -->|"output_flow"| CLIModule

    %% Click Events
    click MCPApp "https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/app.py"
    click ConfigLogging "https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/config.py"
    click Agent "https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/agents/agent.py"
    click CLIModule "https://github.com/lastmile-ai/mcp-agent/tree/main/src/mcp_agent/cli/"
    click AugLLM "https://github.com/lastmile-ai/mcp-agent/tree/main/src/mcp_agent/workflows/llm/"
    click ParallelWF "https://github.com/lastmile-ai/mcp-agent/tree/main/src/mcp_agent/workflows/parallel/"
    click OrchestratorWF "https://github.com/lastmile-ai/mcp-agent/tree/main/src/mcp_agent/workflows/orchestrator/"
    click RouterWF "https://github.com/lastmile-ai/mcp-agent/tree/main/src/mcp_agent/workflows/router/"
    click EvaluatorOptWF "https://github.com/lastmile-ai/mcp-agent/tree/main/src/mcp_agent/workflows/evaluator_optimizer/"
    click SwarmWF "https://github.com/lastmile-ai/mcp-agent/tree/main/src/mcp_agent/workflows/swarm/"
    click MCPServer "https://github.com/lastmile-ai/mcp-agent/tree/main/src/mcp_agent/mcp/"
    click Telemetry "https://github.com/lastmile-ai/mcp-agent/tree/main/src/mcp_agent/telemetry/"
    click Examples "https://github.com/lastmile-ai/mcp-agent/tree/main/examples/"
    click Scripts "https://github.com/lastmile-ai/mcp-agent/tree/main/scripts/"

    %% Styles
    classDef user fill:#FFDEAD,stroke:#000,stroke-width:2px;
    classDef cli fill:#F4A460,stroke:#000,stroke-width:2px;
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef llm fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef workflow fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef mcp fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef telemetry fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef examples fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef scripts fill:#E6E6FA,stroke:#000,stroke-width:2px;
```
