This document provides a high-level introduction to the Magg (MCP Aggregator) system, its architecture, and core components. Magg is a meta-MCP server that acts as a central hub for managing, aggregating, and proxying multiple Model Context Protocol (MCP) servers, enabling Large Language Models (LLMs) to dynamically extend their capabilities at runtime. readme.md1-26
For detailed implementation specifics of the core server functionality, see Core MCP Aggregation System. For information about the interactive browser tool, see MBRO Browser System. For deployment and containerization details, see Development & Deployment.
Magg functions as a "package manager for LLM tools" that allows AI assistants to search for, install, and manage their own capabilities without human intervention. readme.md26-30 It implements the Model Context Protocol as both a server (exposing aggregated tools) and a client (connecting to backend MCP servers), creating a proxy layer that unifies multiple tool sources under a single interface. docs/index.md36-49
Core System Architecture
Sources: pyproject.toml65-67 readme.md16-44 docs/index.md32-58
The Magg ecosystem consists of several interconnected components that work together to provide MCP server aggregation:
| Component | Purpose | Entry Point | Key Classes |
|---|---|---|---|
| Magg Server | Core aggregation server | magg.cli:main | MaggServer, ServerManager |
| MBRO Browser | Interactive MCP client | magg.mbro.cli:main | MCPBrowserCLI, BrowserClient |
| Configuration | Settings and server management | N/A | ConfigManager, MaggConfig |
| Authentication | JWT-based security | magg auth commands | BearerAuthManager |
| Kit Management | Server bundle management | magg kit commands | KitManager |
| Transport Layer | Communication protocols | FastMCP integration | MaggRunner, ProxyMCP |
Sources: pyproject.toml65-67 readme.md30-43 docs/index.md32-58
The following diagram shows how Magg components interact during runtime, mapping system concepts to actual code entities:
Magg Runtime Component Interaction
Sources: pyproject.toml44-56 readme.md30-43 docs/index.md123-145
Magg's primary function is to aggregate multiple MCP servers under a unified interface. It exposes tools from backend servers with configurable prefixes (e.g., calc_add, pw_screenshot) while maintaining the full MCP protocol including notifications, progress updates, and resource management. docs/index.md207-224
The system supports three operational modes through the FastMCP framework: docs/index.md106-121
Configuration changes are automatically detected and applied without server restart through the watchdog-based file monitoring system, enabling runtime server management. readme.md31-35
LLMs can discover, install, and configure new MCP servers autonomously using built-in tools like magg_search_servers, magg_add_server, and magg_smart_configure. readme.md18-26 docs/examples.md8-146
Magg uses a comprehensive CI/CD pipeline that automates testing, building, and publishing. pyproject.toml70-84 readme.md10-13
The build system creates multiple Docker image variants optimized for different deployment scenarios: readme.md125-138
pro): Minimal image with WARNING log level for production use.pre): Same as production with INFO logging for staging.dev): Includes development dependencies and DEBUG logging.Magg supports multiple installation approaches to accommodate different use cases: readme.md45-123
| Method | Command | Use Case |
|---|---|---|
| UV Tool Install | uv tool install magg | Recommended for end users |
| Direct from Git | uvx --from git+https://github.com/sitbon/magg.git magg | Latest development version |
| Docker | docker run ghcr.io/sitbon/magg:latest | Containerized deployment |
| Development | uv sync --dev | Local development setup |
Sources: readme.md52-96 docs/index.md61-87
This multi-layered architecture enables Magg to function as both a development tool for AI researchers and a production-ready service for deploying LLM-powered applications with dynamic capability management.