Streamlined Supervisord process management with AI agent integration through the Model Context Protocol (MCP).
Supervisord MCP provides coding agents with direct access to Supervisord process management through the Model Context Protocol. By offering standardized process control capabilities, it eliminates the complexity of shell command parsing and reduces token consumption for AI agents working in production and development environments.
The Model Context Protocol (MCP) Server for Supervisord. https://supervisord.org/
Stars
4
Tools
—
Uptime
—
MCP Integration Sequence
sequenceDiagram
participant Agent as AI Coding Agent
participant MCP as Supervisord MCP Server
participant Supervisord as Supervisord Daemon
participant Process as Application Process
Agent->>MCP: Request: start_process("webapp")
MCP->>Supervisord: Start process via XML-RPC
Supervisord->>Process: Launch application
Process-->>Supervisord: Process started (PID: 1234)
Supervisord-->>MCP: Process status: RUNNING
MCP-->>Agent: {"status": "ok", "message": "Process started"}
Agent->>MCP: Request: get_logs("webapp", lines=50)
MCP->>Supervisord: Fetch stdout/stderr logs
Supervisord-->>MCP: Log entries
MCP-->>Agent: {"status": "ok", "logs": ["Application started..."]}
What is Supervisord MCP?
Supervisord MCP enables AI coding agents to work more efficiently with production process management, contributing to better deployment reliability and operational efficiency.
Supervisord MCP provides direct process control through the Model Context Protocol, eliminating the overhead of shell commands and reducing token consumption for AI agents managing production and development environments.
Core Features:
AI Integration: Built-in MCP protocol support for coding agents
Production Ready: Based on battle-tested Supervisord process manager
Real-time Monitoring: Process status and log access
Robust Operations: Reliable process lifecycle management
Quick Start
Installation
uv add supervisord-mcp
Basic Usage
# Start a process (requires it to be configured in supervisord.conf)
uv run supervisord-mcp start webapp
# Check what's running
uv run supervisord-mcp list-processes
# View logs
uv run supervisord-mcp logs webapp
# Get system information
uv run supervisord-mcp info
Key Features
🚀 Process Management Made Easy
# Start/stop/restart processes
uv run supervisord-mcp start api
uv run supervisord-mcp stop api
uv run supervisord-mcp restart api
# Get detailed status
uv run supervisord-mcp status api
📊 Comprehensive Monitoring
# List all processes with status
uv run supervisord-mcp list-processes
# View real-time logs
uv run supervisord-mcp logs api --lines 100
uv run supervisord-mcp logs api --stderr
# System information
uv run supervisord-mcp info
🤖 AI Agent Integration
Supervisord MCP includes built-in MCP protocol support, allowing AI agents to manage your processes:
# Start MCP server for AI integration
uv run supervisord-mcp mcp
Configure in your AI agent using the recommended stdio transport:
Note: This tool is designed for production and development environments using MCP's stdio transport method as specified in the MCP documentation. This approach provides secure, direct communication between AI agents and the process manager.
Common Use Cases
Production Web Application
# Configure in supervisord.conf:
[program:webapp]
command=gunicorn app:application
directory=/app
numprocs=4
autostart=true
autorestart=true
# Then manage via Supervisord MCP:
uv run supervisord-mcp start webapp
uv run supervisord-mcp logs webapp
Development Environment
# Configure multiple services in supervisord.conf:
[program:frontend]
command=npm run dev
directory=/app/frontend
autostart=false
[program:backend]
command=python manage.py runserver
directory=/app/backend
autostart=false
# Manage the stack:
uv run supervisord-mcp start frontend
uv run supervisord-mcp start backend
uv run supervisord-mcp list-processes
Microservices
# Multiple services configured in supervisord.conf
uv run supervisord-mcp start auth-service
uv run supervisord-mcp start user-service
uv run supervisord-mcp start notification-service
Why Supervisord MCP?
vs. Circus MCP
Production Focus: Supervisord is designed for production environments
Stability: Battle-tested process supervisor with years of production use
Configuration: Uses standard supervisord.conf for process definitions
Note: AI Agent Integration Limitations
Supervisord's XML-RPC API has constraints for dynamic AI agent process management:
add_process is not supported via API (requires manual config file edit + reload)
stdout/stderr logs require separate API calls
No CPU/memory resource metrics available via API
Starting an already-running process throws ALREADY_STARTED error (not idempotent)
For use cases where AI agents need to dynamically add and monitor processes, Circus MCP offers a more complete API. Supervisord MCP is best suited for integrating with existing Supervisord environments.
vs. systemd
Cross-platform: Works on any system with Python
User-friendly: Simple commands and AI integration
Flexible: Easy configuration and process management
vs. PM2
Python-native: Perfect for Python applications
AI integration: MCP protocol support out of the box
Production proven: Based on widely-used Supervisord
Advanced Features
Process Control
# Standard operations
uv run supervisord-mcp start webapp
uv run supervisord-mcp stop webapp
uv run supervisord-mcp restart webapp
# Get detailed status
uv run supervisord-mcp status webapp
Log Management
# View logs with options
uv run supervisord-mcp logs webapp --lines 100
uv run supervisord-mcp logs webapp --stderr
# Real-time log monitoring (use supervisorctl tail in another terminal)
Configuration Management
# Reload configuration after changes
uv run supervisord-mcp reload
Installation & Setup
System Requirements
Python 3.10 or higher
Supervisord installed and running
Any operating system (Linux, macOS, Windows)
Installation Options
# From PyPI (recommended)
uv add supervisord-mcp
# With pip (alternative)
pip install supervisord-mcp
# From source
git clone https://github.com/aether-platform/supervisord-mcp.git
cd supervisord-mcp
uv sync
Supervisord Setup
Install Supervisord:
pip install supervisor
Create configuration directory:
mkdir -p /etc/supervisor/conf.d
Create main configuration file /etc/supervisor/supervisord.conf:
Important: Supervisord MCP requires the [inet_http_server] configuration block to be enabled with HTTP access. The tool connects to Supervisord via HTTP XML-RPC protocol and does not support Unix domain socket connections.
Start Supervisord:
supervisord -c /etc/supervisor/supervisord.conf
Verify Installation
uv run supervisord-mcp --help
uv run supervisord-mcp info
Configuration
Supervisord MCP works with standard Supervisord configuration. Add your programs to /etc/supervisor/conf.d/:
# Process Management
uv run supervisord-mcp start <name>
uv run supervisord-mcp stop <name>
uv run supervisord-mcp restart <name>
uv run supervisord-mcp status <name>
# Monitoring
uv run supervisord-mcp list-processes
uv run supervisord-mcp logs <name> [--lines N] [--stderr]
uv run supervisord-mcp info
# Configuration
uv run supervisord-mcp reload
# AI Integration
uv run supervisord-mcp mcp
Token Cost Analysis for AI Agents
Reduce tokens, agents work faster. Every token an AI agent spends on process monitoring is a token not spent on solving the actual problem. Research shows that iterative debugging stages consume up to 59.4% of total tokens in agentic workflows (Tokenomics, 2026). By providing structured, concise responses through MCP, we cut the largest cost driver in AI-assisted debugging: unnecessary round trips and unstructured output parsing.
Tool Schema Overhead (Context Residency Cost)
When MCP tools are registered, their schema definitions persist in the conversation context throughout the session.
Item
Est. Tokens
9 tools schema
~1,100 tokens
Per-Call Token Cost
Operation
Request
Response
Total
list_processes (5 procs)
~30
~120-200
~150-230
get_process_status
~40
~100-150
~140-190
get_logs (10 lines)
~50
~150-450
~200-500
get_logs (50 lines)
~50
~750-2,450
~800-2,500
get_logs (100 lines, default)
~50
~1,450-4,950
~1,500-5,000
get_system_info
~30
~50-90
~80-120
start/stop/restart_process
~40
~30-60
~70-100
reload_config
~30
~40-70
~70-100
MCP vs Raw Linux Commands — "Quit Quickly" Investigation
Cost comparison when debugging a process that dies immediately after startup.
We develop tools that enhance developer productivity through AI integration and modern cloud-native technologies. Supervisord MCP is part of our broader ecosystem of development tools designed to streamline the software development lifecycle.
Other Projects
AetherSaaS: SaaS platform management console
AetherCoding: AI-enhanced development environments
AetherOperation: Operations and terminal management tools
Circus MCP: Alternative process management with Circus
Acknowledgments
We extend our heartfelt gratitude to the Supervisord development team for creating such a robust and reliable process management foundation. Their excellent work made this project possible. Supervisord MCP builds upon their solid architecture to bring modern AI agent integration to process management.