Muster: Universal Control Plane for AI Agents

In German, _Muster_ means "pattern" or "sample." This project provides the building blocks for AI agents to discover patterns and collect samples from any digital environment. It gives them a universal protocol to interact with the world.

Muster is a universal control plane built on the Model Context Protocol (MCP) that solves the MCP server management problem for platform engineers and AI agents.

---

The Platform Engineer's Dilemma

As a platform engineer, you interact with countless services: Kubernetes, Prometheus, Grafana, Flux, ArgoCD, cloud providers, and custom tooling. While tools like Terraform and Kubernetes operators provide unified orchestration interfaces, debugging and monitoring still requires jumping between different tools and contexts.

The MCP Revolution: LLM agents (in VSCode, Cursor, etc.) + MCP servers should solve this by giving agents direct access to your tools. There are already many excellent MCP servers available (Kubernetes, Prometheus, Grafana, Flux, etc.).

But there's a problem:

• Adding all MCP servers to your agent pollutes the context and increases costs
• Turning servers on/off manually is tedious and error-prone
• Tool discovery becomes overwhelming as your toolkit grows
• No coordination between different MCP servers and their prerequisites

The Solution: Intelligent MCP Aggregation

Muster solves this by creating a meta-MCP server that manages all your MCP servers and provides your agent with intelligent tool discovery capabilities.

📖 Learn More: MCP Aggregation Deep Dive | System Architecture

How It Works

1. **muster serve** starts the control plane that manages your MCP server processes

2. **Configure muster agent** as an MCP server in your IDE

3. Your agent gets meta-tools like list_tools, filter_tools, call_tool

4. Agent discovers and uses tools dynamically based on the current task

graph TD
    subgraph "Your IDE (VSCode/Cursor)"
        Agent["🤖 AI Agent"]
        IDE["IDE MCP Config"]
    end

    subgraph "Muster Control Plane"
        MusterAgent["🎯 muster agent(Meta-MCP Server)"]
        MusterServe["⚙️ muster serve(Process Manager)"]

        subgraph "Managed MCP Servers"
            K8s["🔷 Kubernetes(kubectl, helm)"]
            Prom["📊 Prometheus(metrics, alerts)"]
            Grafana["📈 Grafana(dashboards)"]
            Flux["🔄 Flux(GitOps)"]
        end
    end

    Agent |"MCP Protocol"| MusterAgent
    MusterAgent  MusterServe
    MusterServe  K8s
    MusterServe  Prom
    MusterServe  Grafana
    MusterServe  Flux

📖 Learn More: Component Interaction Diagram | System Overview

Core Capabilities

🧠 Intelligent Tool Discovery

Your agent can now:

# Discover available tools dynamically
agent: "What Kubernetes tools are available?"
→ filter tools {pattern="kubernetes"}

# Find the right tool for the task
agent: "I need to check pod logs"
→ filter tools {description="logs"}

# Execute tools on-demand
agent: "Show me failing pods in default namespace"
→ call x_kubernetes_list {"resourceType": "pods", "namespace": "default"}

📖 Learn More: MCP Tools Reference | Tool Discovery Guide

🚀 Dynamic MCP Server Management

• Lifecycle Control: Start, stop, restart MCP servers on demand
• Health Monitoring: Automatic health checks and recovery
• Configuration Management: Hot-reload server configurations
• Local Process Deployment: Local processes (local) for MCP server execution

📖 Learn More: MCP Server Management | Configuration Guide

🛡️ Smart Access Control

• Tool Filtering: Block destructive tools by default (override with --yolo)
• Project-Based Control: Different tool sets for different projects
• Context Optimization: Only load tools when needed

📖 Learn More: Security Configuration

🏗️ Advanced Orchestration

Workflows: Deterministic Task Automation

Once your agent discovers how to complete a task, persist it as a workflow:

name: debug-failing-pods
steps:
  - id: find-pods
    tool: x_kubernetes_get_pods
    args:
      namespace: "{{ .namespace }}"
      status: "failed"
  - id: get-logs
    tool: x_kubernetes_get_logs
    args:
      pod: "{{ steps.find-pods.podName }}"
      lines: 100

Benefits:

• Reduce AI costs (deterministic execution)
• Faster results (no re-discovery)
• Consistent debugging across team members

📖 Learn More: Workflow Creation Guide | Workflow Component Architecture

ServiceClasses: Handle Prerequisites Automatically

Many MCP servers need setup (port-forwarding, authentication, etc.). ServiceClasses define these prerequisites:

name: prometheus-access
startTool: x_kubernetes_port_forward
args:
  service: "prometheus-server"
  namespace: "monitoring"
  localPort: 9090
healthCheck:
  url: "http://localhost:9090/api/v1/status"

Complete Integration Example:

1. ServiceClass creates port-forwarding to Prometheus

2. MCP Server configuration uses the forwarded port

3. Workflow orchestrates: setup → query → cleanup

4. Agent executes everything seamlessly

📖 Learn More: ServiceClass Patterns | Service Configuration | Services Component Guide

Quick Start

🤖 AI Agent Users (5 minutes)

Connect Muster to your IDE for smart tool access:

📖 **AI Agent Setup Guide**

🏗️ Platform Engineers (15 minutes)

Set up Muster for infrastructure management:

📖 **Platform Setup Guide**

👩‍💻 Contributors (10 minutes)

Configure your development environment:

📖 **Development Setup**

Installation

Homebrew (macOS)

brew tap giantswarm/muster
brew install muster

Manual Installation

git clone https://github.com/giantswarm/muster.git
cd muster && go build .

📖 Learn More: Installation Guide | Local Demo

Configure MCP Servers

Create kubernetes-server.yaml:

apiVersion: muster.io/v1
kind: MCPServer
name: kubernetes
spec:
  type: localCommand
  command: ["mcp-kubernetes"]
  autoStart: true

Register it:

./muster create mcpserver kubernetes.yaml

Connect Your AI Agent

Configure your IDE to use Muster's agent as an MCP server:

Cursor/VSCode settings.json:

{
  "mcpServers": {
    "muster": {
      "command": "muster",
      "args": ["standalone"]
    }
  }
}

📖 Learn More: AI Agent Integration | Cursor Advanced Setup

Let Your Agent Discover Tools

Your agent now has meta-capabilities:

• **list_tools**: Show all available tools
• **filter_tools**: Find tools by name/description
• **describe_tool**: Get detailed tool information
• **call_tool**: Execute any tool dynamically

📖 Learn More: Complete MCP Tools Reference | CLI Command Reference

Advanced Platform Engineering Scenarios

Scenario 1: Multi-Cluster Debugging

ServiceClass for cluster access

name: cluster-login
version: "1.0.0"
serviceConfig:
  serviceType: "auth"
  args:
    cluster:
      type: "string"
      required: true
  lifecycleTools:
    start: { tool: "x_teleport_kube_login" }

Workflow to compare pods on two clusters

# Workflow for cross-cluster investigation
name: compare-pod-on-staging-prod
input_schema:
  type: "object"
  properties:
    namespace: { type: "string" }
    pod: { type: "string" }
  required: ["namespace", "pod"]
steps:
  - id: staging-context
    tool: core_service_create
    args:
      serviceClassName: "cluster-login"
      name: "staging-context"
      params:
        cluster: "staging"
  - id: prod-context
    tool: core_service_create
    args:
      serviceClassName: "cluster-login"
      name: "staging-context"
      params:
        cluster: "production"
  - id: wait-for-step
  - id: compare-resources
    tool: workflow_compare_pods_on_clusters
    args:

Scenario 2: Full Observability Stack

# Prometheus access with port-forwarding
name: prometheus-tunnel
startTool: k8s_port_forward
args:
  service: "prometheus-server"
  localPort: 9090

---
# Grafana dashboard access
name: grafana-tunnel
startTool: k8s_port_forward
args:
  service: "grafana"
  localPort: 3000
---
# Complete monitoring workflow
name: investigation-setup
steps:
  - id: setup-prometheus
    serviceClass: prometheus-tunnel
  - id: setup-grafana
    serviceClass: grafana-tunnel
  - id: configure-prometheus-mcp
    tool: core_mcpserver_create
    args:
      name: "prometheus"
      type: "localCommand"
      command: ["mcp-server-prometheus"]
      env:
        PROMETHEUS_URL: "http://localhost:9090"

📖 Learn More: Advanced Scenarios | Configuration Examples

Benefits for Platform Teams

Cost Optimization

• Reduced AI token usage: Tools loaded only when needed
• Deterministic workflows: No re-discovery costs
• Efficient context: Smart tool filtering

Team Collaboration

• GitOps workflows: Share debugging patterns via Git
• Consistent tooling: Same tool access across team members
• Knowledge preservation: Workflows capture tribal knowledge

Operational Excellence

• Faster incident response: Pre-built investigation workflows
• Reduced context switching: All tools through one interface
• Automated prerequisites: ServiceClasses handle setup complexity

📖 Learn More: Core Benefits | Design Principles

Documentation Hub

🚀 Getting Started

• Quick Start Guide - Get up and running in minutes
• AI Agent Setup - IDE integration guide
• Platform Setup - Infrastructure setup
• Local Demo - Try Muster locally

🛠️ How-To Guides

• Workflow Creation - Build automation workflows
• ServiceClass Patterns - Manage service dependencies
• MCP Server Management - Configure external tools
• Troubleshooting - Common issues and solutions
• AI Troubleshooting - AI-specific debugging

📚 Reference Documentation

• CLI Commands - Complete command reference
• Configuration - Configuration schemas
• API Reference - REST and MCP APIs
• MCP Tools - Available tools catalog
• CRDs - Kubernetes Custom Resources

🏗️ Architecture & Concepts

• System Architecture - How Muster works
• Component Overview - Individual components
• MCP Aggregation - Core aggregation logic
• Design Decisions - Architecture decisions
• Problem Statement - Why Muster exists

🚀 Operations & Deployment

• Installation - Production deployment
• Security Configuration - Security best practices

👥 Contributing

• Development Setup - Dev environment
• Testing Framework - Testing guidelines
• Code Guidelines - Development standards

Community & Support

• **Contributing Guide**: How to contribute to Muster
• **Issue Tracker**: Bug reports and feature requests
• **Discussions**: Community Q&A and use cases

---

*Muster is a Giant Swarm project, built to empower platform engineers and AI agents with intelligent infrastructure control.*