### Example mbro Script: Development Setup

Source: https://github.com/sitbon/magg/blob/main/docs/mbro.md

An example mbro script (`dev-setup.mbro`) demonstrating how to connect to development servers and check status.

```bash
# Development setup (`dev-setup.mbro`):

# Connect to development servers
connect db npx -y @modelcontextprotocol/server-sqlite -- dev.db
connect fs npx -y @modelcontextprotocol/server-filesystem -- --readonly .
connect git npx -y @modelcontextprotocol/server-git

# Check status
status
tools
```

--------------------------------

### Server Configuration Examples

Source: https://github.com/sitbon/magg/blob/main/docs/index.md

Illustrates different ways to configure servers within the Magg ecosystem, including standard server setup, custom server setups using virtual environments or Docker, and the structure of the .magg/config.json file.

```json
{
  "servers": {
    "calc": {
      "name": "calc",
      "source": "https://github.com/wrtnlabs/calculator-mcp",
      "prefix": "calc",
      "notes": null,
      "command": "npx",
      "args": [
        "-y",
        "@wrtnlabs/calculator-mcp@latest"
      ],
      "uri": null,
      "env": null,
      "cwd": null,
      "transport": null,
      "enabled": true
    }
  }
}
```

```json
{
  "name": "custom-server",
  "source": "file:///path/to/server", 
  "prefix": "custom",
  "command": "uv run python server.py",
  "cwd": "/path/to/server"
}
```

```json
{
  "name": "docker-server",
  "source": "docker://myimage:tag", 
  "prefix": "myimage",
  "command": "docker run -i myimage:tag",
  "env": {
    "DOCKER_HOST": "unix:///var/run/docker.sock"
  }
}
```

--------------------------------

### Get Kit Information

Source: https://github.com/sitbon/magg/blob/main/docs/examples.md

Retrieves detailed information about a specific kit, including all server configurations and metadata. This is useful for understanding the contents and setup of a kit.

```text
mbro:magg> call magg_kit_info name="web-tools"
```

--------------------------------

### Local Development Setup for Magg

Source: https://github.com/sitbon/magg/blob/main/readme.md

Provides instructions for cloning the Magg repository, installing dependencies in editable mode using 'uv' or 'poetry', and running the CLI.

```bash
# 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
```

--------------------------------

### Search Results for Browser Automation Tools

Source: https://github.com/sitbon/magg/blob/main/docs/examples.md

Example JSON output from the `magg_search_servers` tool, listing discovered MCP servers relevant to browser automation, including their source, name, description, URL, and installation command.

```json
{
  "errors": null,
  "output": {
    "query": "browser automation playwright mcp",
    "results": [
      {
        "source": "glama",
        "name": "dex-metrics-mcp",
        "description": "An MCP server that tracks trading volume metrics segmented by DEX, blockchain, aggregator, frontend, and Telegram bot.",
        "url": "https://glama.ai/mcp/servers/g6ba16nv5a",
        "install_command": "git clone https://github.com/kukapay/dex-metrics-mcp"
      },
      ...
    ],
    "total": 9
  }
}
```

--------------------------------

### Generate Server Configuration Prompt

Source: https://github.com/sitbon/magg/blob/main/docs/examples.md

Shows how to use the `configure_server` prompt to get configuration details for an MCP server from a given URL. It outlines the expected input to the prompt and the desired output structure for server configuration.

```text
mbro:magg> prompt configure_server url="https://github.com/microsoft/playwright-mcp"
```

--------------------------------

### Installation Methods

Source: https://github.com/sitbon/magg/blob/main/docs/mbro.md

Provides instructions for installing the mbro tool using different package managers and methods.

```bash
uv tool install magg
```

```bash
poetry add magg
```

```bash
pip install magg
```

```bash
# Run mbro directly
uvx --from magg mbro
```

--------------------------------

### MCP Proxy Tool Examples (JSON)

Source: https://github.com/sitbon/magg/blob/main/docs/proxy.md

Illustrates various ways to use the MCP Proxy Tool by providing JSON request examples for listing tools with and without pagination, filtering by server, getting tool information, and calling tools with different argument formats.

```json
// List all tools (with default pagination: limit=100, offset=0)
{
  "action": "list",
  "type": "tool"
}

// List tools with pagination
{
  "action": "list",
  "type": "tool",
  "limit": 50,
  "offset": 50
}

// List tools from a specific server only
{
  "action": "list",
  "type": "tool",
  "filter_server": "serena_"
}

// Get info about a specific tool
{
  "action": "info", 
  "type": "tool",
  "path": "calculator_add"
}

// Call a tool (with dict args)
{
  "action": "call",
  "type": "tool", 
  "path": "calculator_add",
  "args": {"a": 5, "b": 3}
}

// Call a tool (with JSON string args)
{
  "action": "call",
  "type": "tool",
  "path": "calculator_add", 
  "args": "{\"a\": 5, \"b\": 3}"
}

// Read a resource
{
  "action": "call",
  "type": "resource",
  "path": "config://settings.json"
}
```

--------------------------------

### Prompt for Server Configuration Details

Source: https://github.com/sitbon/magg/blob/main/docs/examples.md

The detailed prompt structure expected by the `configure_server` tool, guiding the LLM to extract specific configuration parameters (name, prefix, command, URI, etc.) from a provided server URL.

```APIDOC
role: system
content: You are an expert at configuring MCP servers. Analyze the provided URL and generate optimal server configuration.

role user
content: Configure an MCP server for: https://github.com/microsoft/playwright-mcp
  
Server name: auto-generate

Please determine:
1. name: A string, potentially user provided (can be human-readable)
2. prefix: A valid Python identifier (no underscores)
3. command: The full command to run (e.g., "python server.py", "npx @playwright/mcp@latest", or null for HTTP)
4. uri: For HTTP servers (if applicable)
5. cwd: If needed
6. env: Environment variables as an object (if needed)
7. notes: Helpful setup instructions
8. transport: Any transport-specific configuration (optional dict)

Consider the URL type:
- GitHub repos may need cloning and setup
- NPM packages use npx
- Python packages may use uvx or python -m
- HTTP/HTTPS URLs may be direct MCP servers
```

--------------------------------

### Custom Kit Example

Source: https://github.com/sitbon/magg/blob/main/docs/kits.md

An example of a custom kit JSON file created by a user, demonstrating personal server configurations.

```json
{
  "name": "my-tools",
  "description": "My personal MCP server collection",
  "author": "Your Name",
  "version": "1.0.0",
  "servers": {
    "tool1": {
      "source": "https://github.com/you/tool1",
      "command": "node",
      "args": ["index.js"],
      "enabled": true
    },
    "tool2": {
      "source": "https://github.com/you/tool2",
      "uri": "http://localhost:8080/mcp",
      "enabled": false
    }
  }
}
```

--------------------------------

### mbro File System Operations Example

Source: https://github.com/sitbon/magg/blob/main/docs/mbro.md

An example showcasing how to connect mbro to a file system server and list/access resources, such as reading the content of the '/etc/hosts' file.

```bash
$ mbro
mbro> connect fs npx -y @modelcontextprotocol/server-filesystem -- --readonly /
Connected to 'fs' (Tools: 3, Resources: 100+, Prompts: 0)

mbro:fs> resources
Available resources:
  - file:///etc/hosts
  - file:///etc/passwd
  - ...

mbro:fs> resource file:///etc/hosts
127.0.0.1   localhost
::1         localhost
...
```

--------------------------------

### Get Server Status

Source: https://github.com/sitbon/magg/blob/main/docs/examples.md

Retrieves an overview of all servers and their current state, including total, enabled, mounted, and disabled servers, as well as tool counts and prefix mappings.

```text
mbro:magg> call magg_status
```

--------------------------------

### Python MaggClient Examples

Source: https://github.com/sitbon/magg/blob/main/docs/authentication.md

Illustrates different ways to use the MaggClient in Python, including auto-loading JWT from environment, explicit token passing, and transparent proxy mode.

```python
import os
from magg.client import MaggClient
from fastmcp.client import BearerAuth

# Method 1: Auto-load from environment
os.environ['MAGG_JWT'] = 'your-jwt-token'
async with MaggClient("http://localhost:8000/mcp") as client:
    tools = await client.list_tools()

# Method 2: Explicit token
auth = BearerAuth('your-jwt-token')
async with MaggClient("http://localhost:8000/mcp", auth=auth) as client:
    tools = await client.list_tools()

# Method 3: Transparent proxy mode (no prefixes)
async with MaggClient("http://localhost:8000/mcp", transparent=True) as client:
    # Call tools without prefixes
    result = await client.call_tool("add", {"a": 5, "b": 3})
    # Instead of: client.call_tool("calc_add", {"a": 5, "b": 3})
```

--------------------------------

### Kit File Example

Source: https://github.com/sitbon/magg/blob/main/docs/index.md

An example JSON file demonstrating the structure of a Magg kit, used for bundling related MCP servers. It includes metadata like name, description, author, version, and a list of servers with their configurations.

```json
{
  "name": "web-tools",
  "description": "Web automation and scraping tools",
  "author": "Your Name",
  "version": "1.0.0",
  "keywords": ["web", "browser", "scraping"],
  "links": {
    "homepage": "https://github.com/example/web-tools-kit"
  },
  "servers": {
    "playwright": {
      "source": "https://github.com/microsoft/playwright-mcp",
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "enabled": true
    },
    "scraper": {
      "source": "https://github.com/example/scraper-mcp",
      "uri": "http://localhost:8080/mcp"
    }
  }
}
```

--------------------------------

### Magg Auth Configuration File

Source: https://github.com/sitbon/magg/blob/main/docs/authentication.md

Example of the `.magg/auth.json` configuration file, specifying bearer authentication parameters like issuer, audience, and key path.

```json
{
  "bearer": {
    "issuer": "https://magg.local",
    "audience": "myapp",
    "key_path": "/custom/path/to/keys"
  }
}
```

--------------------------------

### List Available Kits

Source: https://github.com/sitbon/magg/blob/main/docs/examples.md

Lists all available kits, including their loaded status, description, author, and associated servers. This provides an overview of the kit management system.

```text
mbro:magg> call magg_list_kits
```

--------------------------------

### Example mbro Script: Testing Workflow

Source: https://github.com/sitbon/magg/blob/main/docs/mbro.md

An example mbro script (`test-flow.mbro`) illustrating a testing workflow, including connecting to a test server, running tests, and cleanup.

```bash
# Testing workflow (`test-flow.mbro`):

# Connect to test server
connect test python -m myproject.test_server

# Run test sequence
call setup_test_data
call run_test suite=integration
call get_test_results format=json

# Cleanup
call cleanup_test_data
disconnect
```

--------------------------------

### Quick Install and Run Magg

Source: https://github.com/sitbon/magg/blob/main/readme.md

Installs Magg as a tool using 'uv' and demonstrates how to run it with stdio or HTTP transport.

```bash
# 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
```

--------------------------------

### mbro Calculator Operations Example

Source: https://github.com/sitbon/magg/blob/main/docs/mbro.md

A practical example demonstrating how to connect mbro to a calculator server and use it to perform basic arithmetic operations like addition and division.

```bash
$ mbro
mbro> connect calc npx -y @modelcontextprotocol/server-calculator
Connected to 'calc' (Tools: 4, Resources: 0, Prompts: 0)

mbro:calc> tools
Available tools:
  - add: Add two numbers
  - subtract: Subtract two numbers
  - multiply: Multiply two numbers
  - divide: Divide two numbers

mbro:calc> call add a=42 b=58
100

mbro:calc> call divide a=100 b=4
25
```

--------------------------------

### Initialize Authentication with Custom Parameters

Source: https://github.com/sitbon/magg/blob/main/docs/authentication.md

Shows how to initialize Magg authentication with custom audience, issuer, or key path configurations.

```bash
# Custom audience and issuer
magg auth init --audience myapp --issuer https://mycompany.com

# Custom key location
magg auth init --key-path /opt/magg/keys
```

--------------------------------

### ProxyClient Usage Examples (Python)

Source: https://github.com/sitbon/magg/blob/main/docs/proxy.md

Demonstrates how to use the ProxyClient in both direct and transparent modes to interact with proxy-enabled servers. Includes examples for listing tools, calling tools, and reading resources.

```python
from magg.proxy.client import ProxyClient

# Create a proxy-aware client
async with ProxyClient("http://localhost:8080/mcp") as client:
    # Natural method interface - returns raw proxy tool results
    result = await client.proxy("tool", "list")
    # Result is a list with one EmbeddedResource for query actions
    
    result = await client.proxy("tool", "call", "calculator_add", arguments={"a": 5, "b": 3})
    # Result is the tool's actual output (list of content items)

# Transparent mode - redirects standard methods through proxy
async with ProxyClient("http://localhost:8080/mcp", transparent=True) as client:
    tools = await client.list_tools()  # Uses proxy internally, returns list[Tool]
    result = await client.call_tool("calculator_add", {"a": 5, "b": 3})  # Returns content list
    
    # Resources and prompts work transparently too
    resources = await client.list_resources()  # Returns list[Resource | ResourceTemplate]
    resource_data = await client.read_resource("config://settings.json")
    prompt_result = await client.get_prompt("greeting", {"name": "Alice"})

```

--------------------------------

### Kit File Format Example

Source: https://github.com/sitbon/magg/blob/main/docs/kits.md

An example of the JSON structure for a Magg Kit file, including metadata and server configurations.

```json
{
  "name": "calculator",
  "description": "Basic calculator functionality for MCP",
  "author": "Magg Team",
  "version": "1.0.0",
  "keywords": ["math", "calculator", "arithmetic"],
  "links": {
    "homepage": "https://github.com/example/calculator-kit",
    "docs": "https://github.com/example/calculator-kit/wiki"
  },
  "servers": {
    "calc": {
      "source": "https://github.com/example/mcp-calc-server",
      "command": "python",
      "args": ["-m", "mcp_calc_server"],
      "notes": "Basic calculator server"
    }
  }
}
```

--------------------------------

### Initialize Magg Authentication

Source: https://github.com/sitbon/magg/blob/main/docs/authentication.md

Generates the RSA keypair required for Magg's JWT bearer token authentication. This is a one-time setup process that creates private and public key files.

```bash
magg auth init
```

--------------------------------

### Run Magg directly without installation

Source: https://github.com/sitbon/magg/blob/main/docs/index.md

Executes the Magg server using uvx, allowing direct execution from PyPI or a git repository without a formal installation.

```bash
# From PyPI
uvx magg serve

# From git repository
uvx --from git+https://github.com/sitbon/magg.git magg serve
```

--------------------------------

### Install Magg with uv tool

Source: https://github.com/sitbon/magg/blob/main/docs/index.md

Installs the Magg package using the uv tool, which is the recommended method for installation.

```bash
uv tool install magg
```

--------------------------------

### Magg Configuration File Example

Source: https://github.com/sitbon/magg/blob/main/readme.md

An example JSON structure for Magg's configuration file (`.magg/config.json`), demonstrating how to define servers with their source, command, prefix, and enabled status.

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

--------------------------------

### Load a Kit

Source: https://github.com/sitbon/magg/blob/main/docs/examples.md

Loads a specific kit by its name. This action makes the servers and tools associated with the kit available in the system. The response confirms the kit loaded and lists the added servers.

```text
mbro:magg> call magg_load_kit name="web-tools"
```

--------------------------------

### Install Magg with pip

Source: https://github.com/sitbon/magg/blob/main/docs/index.md

Installs Magg using pip, the standard Python package installer.

```bash
pip install magg
```

--------------------------------

### Basic Usage and Connection

Source: https://github.com/sitbon/magg/blob/main/docs/mbro.md

Demonstrates how to start mbro in interactive mode and connect to MCP servers using different connection strings.

```bash
mbro
```

```bash
mbro> connect memory npx -y @modelcontextprotocol/server-memory
```

```bash
mbro> connect magg http://localhost:8080
```

```bash
mbro> connect myserver python -m mypackage.mcp_server
```

--------------------------------

### Magg Configuration Reload Examples

Source: https://github.com/sitbon/magg/blob/main/docs/index.md

Provides examples of how to trigger Magg's configuration reload. This includes automatic reloading via file changes, manual reloading using the SIGHUP signal, and triggering a reload via an MCP client tool.

```bash
# Start Magg with auto-reload enabled
magg serve --http

# Edit config in another terminal
vim .magg/config.json
# Changes are applied automatically!

# Find Magg process
ps aux | grep magg

# Send SIGHUP to reload
kill -HUP <pid>
```

--------------------------------

### Using Playwright Server Tools

Source: https://github.com/sitbon/magg/blob/main/docs/examples.md

Illustrates how to interact with the newly added Playwright MCP server. It shows how to list available tools and then execute specific Playwright commands like navigating to a URL and taking a screenshot.

```text
mbro:magg> tools
mbro:magg> call playwright_browser_navigate url="https://example.com"
mbro:magg> call playwright_browser_take_screenshot
```

--------------------------------

### Magg Hybrid Mode Example with mbro

Source: https://github.com/sitbon/magg/blob/main/docs/index.md

Demonstrates how mbro can host Magg in hybrid mode and connect to it via stdio, while also allowing other clients to connect via HTTP.

```bash
# mbro can host Magg in hybrid mode and connect to it via stdio
mbro connect magg "magg serve --hybrid --port 8080"

# Now Magg is:
# - Connected to mbro via stdio
# - Also accessible via HTTP at http://localhost:8080

# Other mbro instances can now connect via HTTP
mbro connect magg-remote http://localhost:8080
```

--------------------------------

### Connect with MaggClient (Python)

Source: https://github.com/sitbon/magg/blob/main/docs/authentication.md

Demonstrates how to use the MaggClient in Python to connect to a Magg server with authentication. It shows automatic loading from environment variables.

```python
from magg.client import MaggClient

# Automatically uses MAGG_JWT environment variable
async with MaggClient("http://localhost:8000/mcp") as client:
    tools = await client.list_tools()
```

--------------------------------

### Proxy Tool Actions

Source: https://github.com/sitbon/magg/blob/main/docs/index.md

Provides examples of JSON payloads used to interact with the Magg proxy tool. These examples cover listing tools, calling specific tools with arguments, and reading resources.

```json
{
  "action": "list",
  "type": "tool"
}
```

```json
{
  "action": "call",
  "type": "tool",
  "path": "calc_add",
  "args": {"a": 5, "b": 3}
}
```

```json
{
  "action": "call",
  "type": "resource",
  "path": "file:///example.txt"
}
```

--------------------------------

### Search for Browser Automation Tools

Source: https://github.com/sitbon/magg/blob/main/docs/examples.md

Demonstrates how to search for MCP servers related to browser automation using the `magg_search_servers` tool. It shows the command to execute the search and the expected JSON response structure.

```text
mbro:magg> call magg_search_servers query="browser automation playwright mcp" limit=3
```

--------------------------------

### Magg Server Configuration Environment Variables

Source: https://github.com/sitbon/magg/blob/main/docs/authentication.md

Environment variables for configuring the Magg server, specifically for providing the private key content directly.

```text
MAGG_PRIVATE_KEY: Private key content (takes precedence over file)
  export MAGG_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIE..."
```

--------------------------------

### Add Playwright Server

Source: https://github.com/sitbon/magg/blob/main/docs/examples.md

Demonstrates adding a Playwright MCP server using the `magg_add_server` tool. It includes the command to add the server with its source URL, a chosen name, the execution command, and descriptive notes.

```text
mbro:magg> call magg_add_server \
  source="https://github.com/microsoft/playwright-mcp" \
  name="playwright" \
  command="npx @playwright/mcp@latest" \
  notes="Browser automation MCP server using Playwright."
```

--------------------------------

### Install Magg with Poetry

Source: https://github.com/sitbon/magg/blob/main/docs/index.md

Adds Magg as a dependency to a Python project managed by Poetry.

```bash
poetry add magg
```

--------------------------------

### Magg Client Migration Example

Source: https://github.com/sitbon/magg/blob/main/docs/messaging.md

Provides a comparison between the old and new ways of initializing a MaggClient, highlighting the addition of the `message_handler` parameter for integrating message handling capabilities.

```python
# Before
client = MaggClient("http://localhost:8000")

# After  
handler = MaggMessageHandler(on_tool_list_changed=my_callback)
client = MaggClient("http://localhost:8000", message_handler=handler)
```

--------------------------------

### Run Magg server

Source: https://github.com/sitbon/magg/blob/main/docs/index.md

Starts the Magg server in different modes: stdio, HTTP, or hybrid. The hybrid mode allows simultaneous stdio and HTTP connections.

```bash
# Run Magg server in stdio mode (after installation)
magg serve

# Or for HTTP mode
magg serve --http

# Or for hybrid mode (both stdio and HTTP simultaneously)
magg serve --hybrid
magg serve --hybrid --port 8080  # Custom port

# Or run directly without installation (if you have uvx)
uvx magg serve
```

--------------------------------

### List Available Resources via Proxy Tool

Source: https://github.com/sitbon/magg/blob/main/docs/examples.md

Lists available resources through the proxy tool. Supports filtering by type and limiting the number of results. The response includes resource URIs, MIME types, and annotations about the proxy action.

```text
mbro:magg> call proxy action="list" type="resource" limit=10
```

--------------------------------

### Magg Smart Configuration

Source: https://github.com/sitbon/magg/blob/main/docs/index.md

Intelligently configures a server from a URL using MCP sampling. It can optionally add the server to the configuration after successful setup.

```APIDOC
magg_smart_configure(source: str, server_name: str = None, allow_add: bool = False)
  Intelligently configures a server from a URL using MCP sampling.
  Parameters:
    source (str, required): URL of the server package/repository.
    server_name (str, optional): Preferred name for the server (auto-generated if not provided).
    allow_add (bool, optional): Whether to automatically add the server after configuration (default: False).
  Note: Requires MCP client support for sampling.
```

--------------------------------

### Authentication with JWT Tokens

Source: https://github.com/sitbon/magg/blob/main/docs/mbro.md

Explains how mbro handles JWT authentication for HTTP servers by checking environment variables and provides an example of setting the token.

```bash
# Set authentication token
export MAGG_JWT=$(magg auth token -q)
```

```bash
# Connect to authenticated server
mbro
mbro> connect magg http://localhost:8080
```

--------------------------------

### Manage Magg Keys

Source: https://github.com/sitbon/magg/blob/main/docs/authentication.md

Commands to display public and private keys, useful for backup or verification. The private key can also be exported in a single-line format.

```bash
# Show public key (safe to share)
magg auth public-key

# Show private key (keep secret!)
magg auth private-key

# Export private key in single-line format for env vars
magg auth private-key --oneline
```

--------------------------------

### mbro CLI Commands

Source: https://github.com/sitbon/magg/blob/main/docs/mbro.md

Provides an overview of core mbro commands used for interacting with servers and tools. Includes examples of connecting to different server types, listing available tools, and executing tool calls.

```APIDOC
mbro CLI Commands:

connect <name> <type> [args...]
  Connects to a server. Types include 'filesystem', 'myserver', 'api', 'remote', 'local', 'magg'.
  Arguments vary based on server type (e.g., URL, package name, file path).
  Example: mbro> connect calc npx -y @modelcontextprotocol/server-calculator
  Example: mbro> connect api http://localhost:3000

tools
  Lists all available tools, often grouped by server or functionality.
  Example: mbro:calc> tools

call <tool_name> [arg1=value1 arg2=value2 ...]
  Executes a specific tool with provided arguments.
  Example: mbro:calc> call add a=42 b=58
  Example: mbro:magg> call weather_current location=London

resource <resource_path>
  Retrieves and displays the content of a specified resource.
  Example: mbro:fs> resource file:///etc/hosts

--repl
  Starts mbro in an asynchronous Python REPL mode.
  Example: mbro --repl

# Command Chaining (using ';')
mbro connect myserver python -m mypackage.mcp_server \; tools

# Line Continuation (using '\')
mbro connect arg1="value1" \
         arg2="value2"
```

--------------------------------

### Add Server Response

Source: https://github.com/sitbon/magg/blob/main/docs/examples.md

The JSON response received after successfully adding a server using `magg_add_server`. It confirms the server addition and provides details about the newly added server, including its configuration and status.

```json
{
  "errors": null,
  "output": {
    "action": "server_added",
    "server": {
      "name": "playwright",
      "source": "https://github.com/microsoft/playwright-mcp",
      "prefix": "playwright",
      "command": "npx @playwright/mcp@latest",
      "uri": null,
      "cwd": null,
      "notes": "Browser automation MCP server using Playwright.",
      "enabled": true,
      "mounted": true
    }
  }
}
```

--------------------------------

### Perform Health Checks and Report Status

Source: https://github.com/sitbon/magg/blob/main/docs/examples.md

Checks the responsiveness of servers and reports their health status. It includes parameters for action, timeout, and provides detailed results for each server, including status and any reasons for timeouts.

```text
mbro:magg> call magg_check action="report" timeout=2.0
```

--------------------------------

### MBro Scripting for Workflow Automation

Source: https://github.com/sitbon/magg/blob/main/readme.md

Demonstrates how to create and run MBro scripts to automate Magg workflows. Includes an example script for connecting, checking status, and adding a server.

```bash
# 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
```

--------------------------------

### Capability Discovery via Proxy

Source: https://github.com/sitbon/magg/blob/main/docs/proxy-spec.md

Explains how the proxy tool facilitates dynamic capability discovery, allowing clients to list and get information about available capabilities.

```APIDOC
Capability Discovery:
- Use `action: "list"` to enumerate available capabilities.
- Use `action: "info"` to retrieve detailed metadata for a capability.
- Clients should cache results for performance.
```

--------------------------------

### Running Magg in Different Modes

Source: https://github.com/sitbon/magg/blob/main/readme.md

Explains and demonstrates the three primary modes for running Magg: stdio, HTTP, and hybrid, including examples for integrating with other tools like Claude Code and mbro.

```bash
# 1. Stdio Mode (default)
magg serve

# 2. HTTP Mode
magg serve --http --port 8000

# 3. Hybrid Mode
magg serve --hybrid
magg serve --hybrid --port 8080  # Custom port

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

# Example 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
```

--------------------------------

### Magg Server Management API

Source: https://github.com/sitbon/magg/blob/main/docs/index.md

Provides a comprehensive reference for Magg's server management commands, including adding, removing, listing, enabling, disabling, and reloading server configurations. It details parameters, return values, and usage examples.

```APIDOC
Magg Server Management Commands:

`magg_add_server`
  Add a new MCP server to the configuration.
  Parameters:
    - `name` (str, required): Unique server name.
    - `source` (str, required): URL or URI of the server package/repository (can be a local path).
    - `command` (str, optional): Full command to run (e.g., "npx @playwright/mcp@latest").
    - `prefix` (str, optional): Tool prefix (defaults to server name).
    - `uri` (str, optional): URI for HTTP servers.
    - `env` (dict|str, optional): Environment variables (can be a dict or JSON string).
    - `cwd` (str, optional): Working directory.
    - `notes` (str, optional): Setup notes.
    - `enable` (bool, optional): Whether to enable immediately (default: true).
    - `transport` (dict|str, optional): Transport-specific configuration (can be a dict or JSON string).
  Example:
    ```json
    {
        "name": "playwright",
        "source": "https://github.com/microsoft/playwright-mcp",
        "command": "npx @playwright/mcp@latest",
        "prefix": "pw",
        "notes": "Browser automation tools"
    }
    ```
  Returns:
    ```json
    {
        "action": "server_added",
        "server": {
            "name": "playwright",
            "source": "https://github.com/microsoft/playwright-mcp",
            "prefix": "pw",
            "command": "npx @playwright/mcp@latest",
            "uri": null,
            "cwd": null,
            "notes": "Browser automation tools",
            "enabled": true,
            "mounted": true
        }
    }
    ```

`magg_remove_server`
  Remove a server from the configuration.
  Parameters:
    - `name` (str, required): Name of server to remove.

`magg_list_servers`
  List all configured servers with their status.
  Returns:
    List of server objects with their current status
    ```json
    [
        {
            "name": "calculator",
            "source": "https://github.com/wrtnlabs/calculator-mcp",
            "prefix": "calc",
            "enabled": true,
            "mounted": true,
            "command": "npx -y @wrtnlabs/calculator-mcp@latest"
        }
    ]
    ```

`magg_enable_server` / `magg_disable_server`
  Enable or disable a server without removing it.
  Parameters:
    - `name` (str, required): Server name to enable/disable.

`magg_reload_config`
  Reload configuration from disk and apply changes dynamically.
  Note: This operation may briefly interrupt service for affected servers. Config reload can also be triggered via SIGHUP signal on Unix systems or happens automatically when the config file is modified (if auto-reload is enabled).
  Returns:
    ```json
    {
        "message": "Configuration reloaded successfully",
        "config_path": "/path/to/.magg/config.json",
        "read_only": false
    }
    ```

`magg_status`
  Get server and tool statistics for monitoring and debugging.
  Returns:
    ```json
    {
        "servers": {
            "total": 5,
            "enabled": 4,
            "mounted": 3,
            "disabled": 1
        },
        "tools": {
            "total": 47
        },
        "prefixes": {
            "calculator": "calc",
            "playwright": "pw",
            "filesystem": "fs"
        }
    }
    ```
```

--------------------------------

### Generate Long-Lived Magg Token for CI/CD

Source: https://github.com/sitbon/magg/blob/main/docs/authentication.md

Generates a long-lived Magg token suitable for automated systems like CI/CD pipelines. This example creates a 30-day token with a specific subject and suppresses output.

```bash
# 30-day token for CI
magg auth token --subject "github-actions" --hours 720 --quiet
```

--------------------------------

### Install Magg with uv

Source: https://github.com/sitbon/magg/blob/main/readme.md

Installs the Magg package using the uv package installer, which is recommended for Python 3.12+.

```bash
uv pip install --system --python 3.12 magg
```

--------------------------------

### mbro Working with Magg Example

Source: https://github.com/sitbon/magg/blob/main/docs/mbro.md

Demonstrates connecting mbro to a Magg instance that serves multiple tools (calculator, file system, weather) and interacting with them, including listing tools by group and calling specific tool functions.

```bash
# Terminal 1: Start Magg with multiple servers configured
$ magg serve --http

# Terminal 2: Connect mbro to Magg
$ mbro
mbro> connect magg http://localhost:8000
Connected to 'magg' (Tools: 11, Resources: 5, Prompts: 2)

mbro:magg> tools
Tool Groups:
- calc (6 tools): calc_add, calc_sub, calc_mul, calc_div, calc_mod, calc_sqrt
- fs (3 tools): fs_read, fs_list, fs_search
- weather (2 tools): weather_current, weather_forecast
Total tools: 11

mbro:magg> call calc_add a=10 b=20
30

mbro:magg> call weather_current location=London
{
  "temperature": 15,
  "conditions": "Partly cloudy",
  "humidity": 65
}
```

--------------------------------

### Magg Server and Tool Management Commands

Source: https://github.com/sitbon/magg/blob/main/docs/examples.md

This section details the core commands for interacting with the Magg system, including server status checks, health monitoring, and kit management. These commands allow users to query server states, diagnose issues, and organize server resources.

```APIDOC
magg_status()
  Description: Retrieves an overview of all servers and their current state.
  Returns: JSON object with server and tool statistics.

magg_check(action: str, timeout: float)
  Description: Performs health checks on servers. Can report status or disable unresponsive servers.
  Parameters:
    action: "report" to get status, "disable" to disable unresponsive servers.
    timeout: The timeout in seconds for the health check.
  Returns: JSON object with health check results and actions taken.

proxy(action: str, type: str, path: Optional[str] = None, filter_server: Optional[str] = None, limit: Optional[int] = None)
  Description: Interacts with resources and tools through a proxy interface.
  Parameters:
    action: The action to perform (e.g., "list", "call").
    type: The type of item to interact with (e.g., "resource", "tool").
    path: The path to the resource when action is "call".
    filter_server: Filters tools by a specific server.
    limit: Limits the number of results when listing items.
  Returns: JSON array of resources or tools, or detailed results for specific actions.

magg_list_kits()
  Description: Lists all available kits, their descriptions, and associated servers.
  Returns: JSON object containing a list of kits.

magg_load_kit(name: str)
  Description: Loads a specified kit, making its associated servers available.
  Parameters:
    name: The name of the kit to load.
  Returns: JSON object confirming the kit load and listing added servers.

magg_kit_info(name: str)
  Description: Retrieves detailed information about a specific kit.
  Parameters:
    name: The name of the kit to get information for.
  Returns: JSON object with detailed kit configuration and metadata.
```

--------------------------------

### Discovering and Adding Servers Workflow

Source: https://github.com/sitbon/magg/blob/main/docs/index.md

Illustrates the step-by-step process for discovering new MCP servers and adding them to the Magg configuration. It covers user requests, server search, review, selection, addition, mounting, and tool availability.

```mermaid
graph TD
    A[User Request] --> B[Search for Servers]
    B --> C[Review Results]
    C --> D[Select Server]
    D --> E[Add Server]
    E --> F[Server Mounted]
    F --> G[Tools Available]
```

--------------------------------

### Magg Client Configuration Environment Variables

Source: https://github.com/sitbon/magg/blob/main/docs/authentication.md

Environment variables for client-side authentication in Magg, primarily for setting the JWT token.

```text
MAGG_JWT: JWT token for client authentication
  export MAGG_JWT="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
```

--------------------------------

### Scripting with .mbro files

Source: https://github.com/sitbon/magg/blob/main/docs/mbro.md

Explains how to create and run scripts using `.mbro` files, which contain a sequence of mbro commands.

```bash
# setup.mbro
# Connect to calculator and memory servers
connect calc npx -y @modelcontextprotocol/server-calculator
connect memory npx -y @modelcontextprotocol/server-memory

# Test calculator
switch calc
call add a=5 b=3

# Save result to memory
switch memory
call create_memory content="5 + 3 = 8"
```

```bash
# Execute a script
mbro -x setup.mbro
```

```bash
# Execute multiple scripts
mbro -x init.mbro -x test.mbro
```

--------------------------------

### Resource Objectification Example (Binary/Non-JSON)

Source: https://github.com/sitbon/magg/blob/main/docs/proxy-spec.md

Illustrates the structure for resources that are binary or cannot be parsed as JSON, maintaining their original MIME type.

```json
[
  {
    "type": "resource",
    "resource": {
      "uri": "<original-resource-uri>",
      "mimeType": "image/png",
      "blob": "<base64-encoded-data>"
    },
    "annotations": {
      "proxyType": "resource",
      "proxyAction": "call",
      "proxyPath": "<resource-uri>"
    }
  }
]
```

--------------------------------

### Magg Authentication Setup and Usage

Source: https://github.com/sitbon/magg/blob/main/docs/index.md

Bash commands and Python code snippets for setting up and using Magg's authentication system, which relies on RSA keypairs and JWT tokens. This includes initializing authentication, checking status, generating tokens, and connecting clients.

```bash
# Initialize authentication (one-time setup):
magg auth init

# Check authentication status:
magg auth status

# Generate JWT tokens for clients
# Display token on screen
magg auth token

# Export to environment variable
export MAGG_JWT=$(magg auth token -q)

# Generate with custom parameters
magg auth token --subject "my-app" --hours 72 --scopes "read" "write"
```

```python
from magg.client import MaggClient

# Automatically uses MAGG_JWT environment variable
async with MaggClient("http://localhost:8000/mcp") as client:
    tools = await client.list_tools()

from fastmcp import Client
from fastmcp.client import BearerAuth

# With explicit token
jwt_token = "your-jwt-token"
auth = BearerAuth(jwt_token)
async with Client("http://localhost:8000/mcp", auth=auth) as client:
    tools = await client.list_tools()
```

--------------------------------

### Check Magg Authentication Status

Source: https://github.com/sitbon/magg/blob/main/docs/authentication.md

Command to check the current authentication status, including configuration details and key file locations.

```bash
magg auth status
```

--------------------------------

### Generate Magg Token with Custom Claims

Source: https://github.com/sitbon/magg/blob/main/docs/authentication.md

Generates a Magg authentication token with custom claims, such as scopes, which can be used for client-side logic enforcement.

```bash
magg auth token --scopes "projects:read" "servers:write"
```

--------------------------------

### Authenticated Request with curl

Source: https://github.com/sitbon/magg/blob/main/docs/authentication.md

Shows how to make an authenticated request to the Magg server using curl by including the JWT token in the Authorization header.

```bash
# Get JWT token
JWT=$(magg auth token -q)

# Make authenticated request
curl -H "Authorization: Bearer $JWT" http://localhost:8000/mcp/
```

--------------------------------

### Basic Magg Client Usage

Source: https://github.com/sitbon/magg/blob/main/docs/index.md

Demonstrates how to initialize and use the MaggClient with a message handler to receive notifications and interact with backend servers. It shows setting up callbacks for specific notification types and performing basic operations like listing tools.

```python
from magg import MaggClient, MaggMessageHandler

# Create message handler with callbacks
handler = MaggMessageHandler(
    on_tool_list_changed=lambda notif: print("Tools changed!"),
    on_progress=lambda notif: print(f"Progress: {notif.progress}")
)

# Create client with message handling
client = MaggClient("http://localhost:8000", message_handler=handler)

async with client:
    # All notifications from backend servers automatically forwarded
    tools = await client.list_tools()
```