Orchestrate MCP Servers for LLM Autonomy

🧲 Magg - The MCP Aggregator

A Model Context Protocol server that manages, aggregates, and proxies other MCP servers, enabling LLMs to dynamically extend their own capabilities.

What is Magg?

Magg is a meta-MCP server that acts as a central hub for managing multiple MCP servers. It provides tools that allow LLMs to:

• Search for new MCP servers and discover setup instructions
• Add and configure MCP servers dynamically
• Enable/disable servers on demand
• Aggregate tools from multiple servers under unified prefixes
• Persist configurations across sessions

Think of Magg as a "package manager for LLM tools" - it lets AI assistants install and manage their own capabilities at runtime.

Features

• Self-Service Tool Management: LLMs can search for and add new MCP servers without human intervention.
• Dynamic Configuration Reloading: Automatically detects and applies config changes without restarting.
• Automatic Tool Proxying: Tools from added servers are automatically exposed with configurable prefixes.
• ProxyMCP Tool: A built-in tool that proxies the MCP protocol to itself, for clients that don't support notifications or dynamic tool updates (which is most of them currently).
• Smart Configuration: Uses MCP sampling to intelligently configure servers from just a URL.
• Persistent Configuration: Maintains server configurations in .magg/config.json.
• Multiple Transport Support: Works with stdio, HTTP, and in-memory transports.
• Bearer Token Authentication: Optional RSA-based JWT authentication for secure HTTP access.
• Docker Support: Pre-built images for production, staging, and development workflows.
• Health Monitoring: Built-in magg_status and magg_check tools for server health checks.
• Real-time Messaging: Full support for MCP notifications and messages - receive tool/resource updates and progress notifications from backend servers.
• Python 3.12+ Support: Fully compatible with Python 3.12 and 3.13.
• Kit Management: Bundle related MCP servers into kits for easy loading/unloading as a group.
• MBro CLI: Included MCP Browser for interactive exploration and management of MCP servers, with script support for automation.

Installation

Prerequisites

• Python 3.12 or higher (3.13+ recommended)
• uv (recommended) - Install from astral.sh/uv

Quick Install (Recommended)

The easiest way to install Magg is as a tool using uv:

# Install Magg as a tool
uv tool install magg

# Run with stdio transport (for Claude Desktop, Cline, etc.)
magg serve

# Run with HTTP transport (for system-wide access)
magg serve --http

Alternative: Run Directly from GitHub

You can also run Magg directly from GitHub without installing:

# Run with stdio transport
uvx --from git+https://github.com/sitbon/magg.git magg

# Run with HTTP transport
uvx --from git+https://github.com/sitbon/magg.git magg serve --http

Local Development

For development, clone the repository and install in editable mode:

# Clone the repository
git clone https://github.com/sitbon/magg.git
cd magg

# Install in development mode with dev dependencies
uv sync --dev

# Or with poetry
poetry install --with dev

# Run the CLI
magg --help

Docker

Magg is available as pre-built Docker images from GitHub Container Registry:

# Run production image (WARNING log level)
docker run -p 8000:8000 ghcr.io/sitbon/magg:latest

# Run with authentication (mount or set private key)
docker run -p 8000:8000 \
  -v ~/.ssh/magg:/home/magg/.ssh/magg:ro \
  ghcr.io/sitbon/magg:latest

# Or with environment variable
docker run -p 8000:8000 \
  -e MAGG_PRIVATE_KEY="$(cat ~/.ssh/magg/magg.key)" \
  ghcr.io/sitbon/magg:latest

# Run beta image (INFO log level)
docker run -p 8000:8000 ghcr.io/sitbon/magg:beta

# Run with custom config directory
docker run -p 8000:8000 \
  -v /path/to/config:/home/magg/.magg \
  ghcr.io/sitbon/magg:latest

Docker Image Strategy

Magg uses a multi-stage Docker build with three target stages:

• pro (Production): Minimal image with WARNING log level, suitable for production deployments
• pre (Pre-production): Same as production but with INFO log level for staging/testing (available but not published)
• dev (Development): Includes development dependencies and DEBUG logging for troubleshooting

Images are automatically published to GitHub Container Registry with the following tags:

• Version tags (from main branch): 1.2.3, 1.2, dev, 1.2-dev, 1.2-dev-py3.12, etc.
• Branch tags (from beta branch): beta, beta-dev
• Python-specific dev tags: beta-dev-py3.12, beta-dev-py3.13, etc.

Pull requests build and test images but do not publish them unless a maintainer adds the push-image label, which publishes ephemeral pr-NN / pr-NN-dev tags (same-repo PRs only). Ephemeral pr-* tags and untagged manifests are cleaned up weekly; version tags are kept forever, so pinned deployments are never affected.

Docker Compose

For easier management, use Docker Compose:

# Clone the repository
git clone https://github.com/sitbon/magg.git
cd magg

# Run production version
docker compose up magg

# Run staging version (on port 8001)
docker compose up magg-beta

# Run development version (on port 8008)
# This uses ./.magg/config.json for configuration
docker compose up magg-dev

# Build and run with custom registry
REGISTRY=my.registry.com docker compose build
REGISTRY=my.registry.com docker compose push

See compose.yaml and .env.example for configuration options.

Usage

Running Magg

Magg can run in three modes:

1. Stdio Mode (default) - For integration with Claude Desktop, Cline, Cursor, etc.:

   magg serve
   

2. HTTP Mode - For system-wide access or web integrations:

   magg serve --http --port 8000
   

3. Hybrid Mode - Both stdio and HTTP simultaneously:

   magg serve --hybrid
   magg serve --hybrid --port 8080  # Custom port
   

   This is particularly useful when you want to use Magg through an MCP client while also allowing HTTP access. For example:

   With Claude Code:

   # Configure Claude Code to use Magg in hybrid mode
   claude mcp add magg -- magg serve --hybrid --port 42000
   

   With mbro:

   # mbro hosts Magg and connects via stdio
   mbro connect magg "magg serve --hybrid --port 8080"
   
   # Other mbro instances can connect via HTTP
   mbro connect magg http://localhost:8080
   

Available Tools

Once Magg is running, it exposes the following tools to LLMs:

• magg_list_servers - List all configured MCP servers
• magg_add_server - Add a new MCP server
• magg_remove_server - Remove a server
• magg_enable_server / magg_disable_server - Toggle server availability
• magg_search_servers - Search for MCP servers online
• magg_list_tools - List all available tools from all servers
• magg_smart_configure - Intelligently configure a server from a URL
• magg_analyze_servers - Analyze configured servers and suggest improvements
• magg_status - Get server and tool statistics
• magg_check - Health check servers with repair actions (report/remount/unmount/disable)
• magg_reload_config - Reload configuration from disk and apply changes
• magg_load_kit - Load a kit and its servers into the configuration
• magg_unload_kit - Unload a kit and optionally its servers from the configuration
• magg_list_kits - List all available kits with their status
• magg_kit_info - Get detailed information about a specific kit

Quick Inspection with MBro

Magg includes the mbro (MCP Browser) CLI tool for interactive exploration. A unique feature is the ability to connect to Magg in stdio mode for quick inspection:

# Connect mbro to a Magg instance via stdio (no HTTP server needed)
mbro connect local-magg magg serve

# Now inspect your Magg setup from the MCP client perspective
mbro:local-magg> call magg_status
mbro:local-magg> call magg_list_servers

MBro also supports:

• Scripts: Create .mbro files with commands for automation
• Shell-style arguments: Use key=value syntax instead of JSON
• Tab completion: Rich parameter hints after connecting

See the MBro Documentation for details.

Authentication

Magg supports optional bearer token authentication to secure access:

Quick Start

1. Initialize authentication (creates RSA keypair):

   magg auth init
   

2. Generate a JWT token for clients:

   # Generate token (displays on screen)
   magg auth token
   
   # Export as environment variable
   export MAGG_JWT=$(magg auth token -q)
   

3. Connect with authentication:

   • Using MaggClient (auto-loads from MAGG_JWT):

     from magg.client import MaggClient
     
     async def main():
         async with MaggClient("http://localhost:8000/mcp") as client:
             tools = await client.list_tools()
     

   • Using FastMCP with explicit token:

     from fastmcp import Client
     from fastmcp.client import BearerAuth
     
     jwt_token = "your-jwt-token-here"
     async with Client("http://localhost:8000/mcp", auth=BearerAuth(jwt_token)) as client:
         tools = await client.list_tools()
     

Key Management

• Keys are stored in ~/.ssh/magg/ by default
• Private key can be set via MAGG_PRIVATE_KEY environment variable
• To disable auth, remove keys or set non-existent key_path in .magg/auth.json

Authentication Commands

• magg auth init - Initialize authentication (generates RSA keypair)
• magg auth status - Check authentication configuration
• magg auth token - Generate JWT token
• magg auth public-key - Display public key (for verification)
• magg auth private-key - Display private key (for backup)

See examples/authentication.py for more usage patterns.

Configuration

Magg stores its configuration in .magg/config.json in your current working directory. This allows for project-specific tool configurations.

Dynamic Configuration Reloading

Magg supports automatic configuration reloading without requiring a restart:

• Automatic file watching: Detects changes to config.json and reloads automatically (uses watchdog when available)
• SIGHUP signal: Send kill -HUP <pid> to trigger immediate reload (Unix-like systems)
• MCP tool: Use magg_reload_config tool from any MCP client
• Smart transitions: Only affected servers are restarted during reload

Configuration reload is enabled by default. You can control it with:

• MAGG_AUTO_RELOAD=false - Disable automatic reloading
• MAGG_RELOAD_POLL_INTERVAL=5.0 - Set polling interval in seconds (when watchdog unavailable)

See Configuration Reload Documentation for detailed information.

Environment Variables

Magg supports several environment variables for configuration:

• MAGG_CONFIG_PATH - Path to config file (default: .magg/config.json)
• MAGG_LOG_LEVEL - Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL (default: INFO)
• MAGG_STDERR_SHOW=1 - Show stderr output from subprocess MCP servers (default: suppressed)
• MAGG_AUTO_RELOAD - Enable/disable config auto-reload (default: true)
• MAGG_RELOAD_POLL_INTERVAL - Config polling interval in seconds (default: 1.0)
• MAGG_READ_ONLY=true - Run in read-only mode
• MAGG_SELF_PREFIX - Prefix for Magg tools (default: "magg"). Tools will be named as {prefix}{sep}{tool} (e.g., magg_list_servers)
• MAGG_PREFIX_SEP - Separator between Magg's prefix and its tool names (default: "_"). Backend server tools always use _
• MAGG_BACKEND_INIT_TIMEOUT - Seconds to wait for a backend server to start before giving up on it (default: 30, 0 waits forever)

Example configuration:

{
  "servers": {
    "calculator": {
      "name": "calculator",
      "source": "https://github.com/executeautomation/calculator-mcp",
      "command": "npx @executeautomation/calculator-mcp",
      "prefix": "calc",
      "enabled": true
    }
  }
}

Adding Servers

Servers can be added in several ways:

1. Using the LLM (recommended):

   "Add the Playwright MCP server"
   "Search for and add a calculator tool"
   

2. Manual configuration via magg_add_server:

   name: playwright
   url: https://github.com/microsoft/playwright-mcp
   command: npx @playwright/mcp@latest
   prefix: pw
   

3. The magg server CLI (see below)

4. Direct config editing: Edit .magg/config.json directly

Managing Servers from the CLI

Server and kit configuration can be managed entirely from the command line - no MCP client or running server required. The CLI edits .magg/config.json directly, and a running Magg instance picks up the changes automatically via config reload. (Tools that require a live server, like magg_search_servers, magg_check, and magg_smart_configure, remain available through any MCP client such as mbro.)

# List servers (human-readable, or JSON on stdout for scripting)
magg server list
magg server list --json

# Add a server
magg server add playwright https://github.com/microsoft/playwright-mcp \
    --command "npx @playwright/mcp@latest" --prefix pw

# Add a server without enabling it, with transport options
magg server add web https://example.com/web --uri http://localhost:9000/mcp \
    --transport '{"keep_alive": false}' --disable

# Update an existing server (pass '' to clear an optional field)
magg server update playwright --prefix play --notes "Browser automation"
magg server update playwright --command "npx @playwright/mcp@next"
magg server update playwright --notes ""

# Enable / disable / inspect / remove
magg server enable playwright
magg server disable playwright
magg server info playwright --json
magg server remove playwright

Real-time Notifications with MaggClient

The MaggClient now supports real-time notifications from backend MCP servers:

from magg import MaggClient, MaggMessageHandler

# Using callbacks
handler = MaggMessageHandler(
    on_tool_list_changed=lambda n: print("Tools changed!"),
    on_progress=lambda n: print(f"Progress: {n.params.progress}")
)

async with MaggClient("http://localhost:8000/mcp", message_handler=handler) as client:
    # Client will receive notifications while connected
    tools = await client.list_tools()

See Messaging Documentation for advanced usage including custom message handlers.

Kit Management

Magg supports organizing related MCP servers into "kits" - bundles that can be loaded and unloaded as a group:

# List available kits
magg kit list

# Load a kit (adds all its servers)
magg kit load web-tools

# Unload a kit (removes servers only in that kit)
magg kit unload web-tools

# Get information about a kit
magg kit info web-tools

# Export the current configuration (or a loaded kit) as a kit file
magg kit export --name my-kit --output my-kit.json

When unloading a kit, servers that belong only to that kit are removed, while servers shared with other kits are kept.

You can also manage kits programmatically through Magg's tools when connected via an MCP client:

• magg_list_kits - List all available kits
• magg_load_kit - Load a kit and its servers
• magg_unload_kit - Unload a kit
• magg_kit_info - Get detailed kit information

Kits are JSON files stored in ~/.magg/kit.d/ or .magg/kit.d/ that define a collection of related servers. See Kit Documentation for details on creating and managing kits.

MBro Scripts

Automate common workflows with MBro scripts:

# Create a setup script
cat > setup.mbro <<EOF
# Connect to Magg and check status
connect magg magg serve
call magg_status
call magg_list_servers

# Add a new server if needed
call magg_add_server name=calculator source="npx -y @modelcontextprotocol/server-calculator"
EOF

# Run the script
mbro -x setup.mbro

MCP 2026-07-28 (Stateless Spec)

The MCP 2026-07-28 spec moves the protocol to a stateless request/response core. Magg's take: something still has to own long-lived stdio subprocesses, backend connections, and tool-list caching - and that's exactly the layer an aggregator provides. See Magg and the Stateless MCP Spec for the impact analysis and migration plan, including how Magg bridges pre-2026 (stateful) backends to stateless-era clients and how hierarchical Magg deployments fit in.

Documentation

For more documentation, see docs/.

Appearances

Magg appears in multiple locations. Please feel free to submit a PR to add more appearances below in alphabetical order.

Listing, Index, and other MCP Sites

• DeepWiki - AI-generated documentation
• Glama.ai - MCP server listing and hosting

Magg ships a server.json manifest for the official MCP Registry (as io.github.sitbon/magg), and magg_search_servers queries the registry as a first-class discovery source alongside Glama, GitHub, and npm. See MCP Registry Documentation for publishing instructions.

mcp-name: io.github.sitbon/magg

Awesome GitHub MCP Lists

• @modelcontextprotocol/servers
• @punkpeye/awesome-mcp-servers
• @wong2/awesome-mcp-servers

examples/authentication.py

#!/usr/bin/env python3
"""Example of connecting to MCP servers with authentication.

This script demonstrates:
1. Bearer token authentication with configurable environment variables
2. Direct token passing
3. Using the MaggClient for automatic authentication
"""

import argparse
import asyncio
import logging
import os
import sys
from typing import Any

from fastmcp import Client
from fastmcp.client import BearerAuth

from magg.client import MaggClient


async def bearer_auth(args: argparse.Namespace) -> None:
    """Test bearer token authentication with configurable options."""
    jwt = args.token
    if not jwt:
        jwt = os.environ.get(args.env_var)
        if not jwt:
            print(f"Error: No JWT token provided. Set {args.env_var} or use --token", file=sys.stderr)
            sys.exit(1)

    print(f"Connecting to {args.url} with bearer token authentication...")

    if args.magg:
        # Use MaggClient
        print(f"Using MaggClient{' with provided token' if args.token else f' (loading from {args.env_var})'}")

        # If using custom env var, set MAGG_JWT for MaggClient
        if args.env_var != "MAGG_JWT" and not args.token:
            os.environ["MAGG_JWT"] = jwt

        if args.token:
            auth = BearerAuth(args.token)
            client = MaggClient(args.url, auth=auth)
        else:
            # Let MaggClient handle auth from MAGG_JWT env var
            client = MaggClient(args.url)

        async with client:
            print(f"Transparent proxy mode: {client._transparent}")

            # Test the connection
            await check_client_capabilities(client)

            # Test proxy-specific functionality if available
            try:
                print("\nTesting proxy functionality...")
                tools = await client.proxy("tool", "list")
                print(f"Proxy list returned {len(tools)} items")
            except Exception as e:
                print(f"Proxy functionality not available: {e}")
    else:
        # Use regular FastMCP Client
        print("Using FastMCP Client")
        auth = BearerAuth(jwt)

        async with Client(args.url, auth=auth) as client:
            # Test the connection
            await check_client_capabilities(client)


async def check_client_capabilities(client: Any) -> None:
    """Test basic MCP client capabilities."""
    # List available tools
    tools = await client.list_tools()
    print(f"\nFound {len(tools)} tools:")
    for tool in tools[:5]:  # Show first 5 tools
        print(f"  - {tool.name}: {tool.description}")
    if len(tools) > 5:
        print(f"  ... and {len(tools) - 5} more")

    # List resources
    try:
        resources = await client.list_resources()
        print(f"\nFound {len(resources)} resources")
    except Exception as e:
        print(f"\nResource listing not available: {e}")

    # List prompts
    try:
        prompts = await client.list_prompts()
        print(f"\nFound {len(prompts)} prompts")
    except Exception as e:
        print(f"\nPrompt listing not available: {e}")

    # Call a simple tool if available
    if tools:
        # Look for a simple info/status tool
        info_tools = [t for t in tools if "status" in t.name.lower() or "info" in t.name.lower()]
        if info_tools:
            tool = info_tools[0]
            print(f"\nCalling tool: {tool.name}")
            try:
                result = await client.call_tool(tool.name)
                print(f"Result: {result[:200]}..." if len(str(result)) > 200 else f"Result: {result}")
            except Exception as e:
                print(f"Tool call failed: {e}")


def create_parser() -> argparse.ArgumentParser:
    """Create command line parser."""
    parser = argparse.ArgumentParser(
        description="Test MCP server authentication",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  # Test with bearer token from environment
  %(prog)s bearer

  # Test with custom URL
  %(prog)s bearer http://localhost:9000

  # Test with custom environment variable
  %(prog)s bearer --env-var MY_TOKEN

  # Test with direct token
  %(prog)s bearer --token "eyJ..."

  # Test using MaggClient (auto-loads from MAGG_JWT)
  %(prog)s bearer --magg

  # Test MaggClient with direct token
  %(prog)s bearer --magg --token "eyJ..."
""",
    )

    parser.add_argument("--debug", action="store_true", help="Enable debug output")

    subparsers = parser.add_subparsers(dest="auth_type", help="Authentication type")

    # Bearer authentication subcommand
    bearer_parser = subparsers.add_parser("bearer", help="Test bearer token authentication")
    bearer_parser.add_argument(
        "url",
        nargs="?",
        default="http://localhost:8000/mcp",
        help="MCP server URL (default: http://localhost:8000/mcp)",
    )
    bearer_parser.add_argument(
        "--env-var", default="MAGG_JWT", help="Environment variable name for JWT (default: MAGG_JWT)"
    )
    bearer_parser.add_argument("--token", help="JWT token (overrides environment variable)")
    bearer_parser.add_argument("--magg", action="store_true", help="Use MaggClient instead of regular FastMCP Client")

    return parser


async def main():
    """Main entry point."""
    parser = create_parser()
    args = parser.parse_args()

    if args.debug:
        logging.basicConfig(level=logging.DEBUG)

    # Check if subcommand was provided
    if not args.auth_type:
        parser.print_help()
        sys.exit(1)

    try:
        if args.auth_type == "bearer":
            await bearer_auth(args)
    except KeyboardInterrupt:
        print("\nInterrupted by user")
        sys.exit(130)
    except Exception as e:
        print(f"\nError: {e}", file=sys.stderr)
        if args.debug:
            import traceback

            traceback.print_exc()
        sys.exit(1)


if __name__ == "__main__":
    asyncio.run(main())