multi-server mcp aggregation with unified tool namespace
Magg implements a hub-and-spoke proxy architecture that connects to multiple backend MCP servers and exposes their tools through a single aggregated interface. It uses configurable tool prefixes (e.g., calc_add, pw_screenshot) to namespace tools from different servers, maintains full MCP protocol semantics including notifications and progress updates, and routes incoming tool calls to the appropriate backend server based on prefix matching. The MaggServer class acts as both an MCP server (exposing aggregated tools) and MCP client (connecting to backends), creating a transparent proxy layer that unifies heterogeneous tool sources.
Unique: Implements bidirectional MCP protocol (both server and client) in a single process to create a transparent aggregation layer, using configurable prefix-based routing to namespace tools from heterogeneous backends while preserving full MCP semantics including notifications and resource management
vs alternatives: Unlike manual MCP server composition, Magg provides automatic tool discovery and aggregation with conflict-free namespacing, and unlike monolithic tool registries, it maintains loose coupling by proxying to independent backend servers
dynamic configuration hot-reloading with watchdog file monitoring
Magg uses watchdog-based file system monitoring to detect configuration changes in real-time and applies them without requiring server restart. The reload.py module watches the configuration file for modifications and triggers ConfigManager to parse updated server definitions, transport settings, and authentication rules. When changes are detected, the system gracefully updates the ServerManager's internal state, reconnecting to modified backends and re-exposing updated tool definitions to connected clients. This enables runtime configuration drift without service interruption.
Unique: Implements watchdog-based file monitoring integrated with ConfigManager to detect and apply configuration changes at runtime without server restart, maintaining active client connections while updating backend server definitions and tool namespaces
vs alternatives: Compared to static configuration approaches, Magg enables runtime updates without service interruption; compared to API-based configuration, file-based monitoring is simpler to implement and audit
cli command interface for server management and configuration operations
Magg provides a comprehensive CLI interface (magg.cli module) with commands for starting the aggregation server, managing authentication, configuring kits, and inspecting server status. The CLI supports subcommands for auth token generation, kit installation/updates, server health checks, and configuration validation. The command processing system parses arguments, validates inputs, and executes operations with formatted output. This enables operators to manage Magg deployments from the command line without requiring programmatic access.
Unique: Provides a comprehensive CLI interface with subcommands for server startup, authentication, kit management, and status inspection, enabling command-line-based management of Magg deployments without programmatic access
vs alternatives: Unlike programmatic APIs, the CLI is accessible to non-developers; unlike web UIs, the CLI integrates easily into scripts and CI/CD pipelines
docker containerization and deployment with environment-based configuration
Magg includes Docker support for containerized deployment, with Dockerfile definitions and docker-compose configurations for multi-container setups. The system uses environment variables for configuration, enabling container orchestration platforms (Kubernetes, Docker Swarm) to inject settings at runtime without rebuilding images. The Docker setup includes health checks, volume mounts for configuration files, and network configuration for multi-container deployments. This enables easy deployment to cloud platforms and container orchestration systems.
Unique: Provides Docker containerization with environment-based configuration, enabling deployment to container orchestration platforms without image rebuilds, with integrated health checks and multi-container support
vs alternatives: Unlike manual deployment, Docker containerization ensures reproducible environments; unlike static configuration, environment variables enable runtime configuration without image rebuilds
transport-agnostic server communication with stdio/http/hybrid modes
Magg abstracts transport layer complexity through FastMCP integration, supporting three operational modes: stdio (direct process pipes for desktop clients), HTTP (REST API for web/browser access), and hybrid (both simultaneously). The transport layer automatically handles protocol translation between MCP JSON-RPC format and the underlying transport mechanism, allowing the same MaggServer instance to serve multiple client types without code changes. The system selects transport based on configuration and can dynamically switch or add transports without restarting the core aggregation logic.
Unique: Abstracts transport complexity through FastMCP integration, allowing the same MaggServer aggregation logic to operate simultaneously in stdio, HTTP, and hybrid modes without code duplication, with automatic protocol translation between JSON-RPC and transport-specific formats
vs alternatives: Unlike single-transport MCP servers, Magg supports multiple transports simultaneously; unlike custom transport adapters, FastMCP integration provides battle-tested protocol handling and reduces implementation burden
autonomous mcp server discovery and installation with package manager semantics
Magg implements package manager semantics for MCP servers, enabling LLMs to autonomously search for, evaluate, and install new servers from a registry without human intervention. The system maintains a searchable registry of available MCP servers with metadata (description, capabilities, dependencies), exposes search and install tools to the LLM, and handles dependency resolution, version management, and server lifecycle setup. When an LLM requests a new capability, it can discover matching servers, review their capabilities, and trigger installation which updates the configuration and reconnects the aggregator to the new backend.
Unique: Implements package manager semantics for MCP servers, exposing discovery and installation as LLM-callable tools that enable autonomous capability expansion, with registry-based server metadata and dependency resolution to support self-improving agent systems
vs alternatives: Unlike static tool configurations, Magg enables runtime capability discovery and installation; unlike manual package managers, it integrates directly into the LLM's decision-making loop, allowing agents to autonomously extend themselves
message routing and protocol proxying with semantic preservation
Magg implements a message routing system that transparently proxies MCP protocol messages (tool calls, resources, prompts, notifications) from clients to appropriate backend servers based on tool prefix matching. The routing layer preserves full MCP semantics including streaming responses, progress updates, and resource references, translating between the aggregated namespace (prefixed tools) and backend namespaces (unprefixed tools). The system maintains request-response correlation to ensure responses are correctly routed back to clients, and handles protocol-level features like sampling, notifications, and resource subscriptions across server boundaries.
Unique: Implements semantic-preserving message routing that maintains full MCP protocol semantics (streaming, notifications, resources) across server boundaries, with automatic prefix-based routing and request-response correlation to transparently proxy heterogeneous backend servers
vs alternatives: Unlike simple tool aggregation, Magg preserves advanced MCP features like streaming and notifications; unlike manual routing logic, the routing layer is transparent to clients and automatically handles namespace translation
jwt-based authentication and bearer token authorization for aggregated tools
Magg implements JWT-based authentication through the BearerAuthManager class, enabling fine-grained access control over aggregated tools. The system validates bearer tokens in incoming requests, decodes JWT claims to extract user identity and permissions, and enforces authorization rules that determine which tools each user can access. The authentication layer integrates with the tool routing system to filter available tools based on user permissions, and supports token refresh and expiration policies. This enables multi-tenant deployments where different users have different tool access levels.
Unique: Implements JWT-based bearer token authentication integrated with tool routing to enforce per-user access control over aggregated tools, enabling multi-tenant deployments with fine-grained authorization without requiring separate authentication services
vs alternatives: Unlike API key-based authentication, JWT enables stateless authorization with embedded claims; unlike external auth services, Magg's built-in authentication reduces deployment complexity for single-aggregator deployments
+4 more capabilities