How lastmile-ai/mcp-agent works
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.