Supervisord MCP

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.

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..."]}

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.

- 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

# 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

# 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

# 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

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 therecommended stdio transport:

{ "mcpServers": { "supervisord-mcp": { "command": "uv", "args": ["run", "supervisord-mcp", "mcp"], "cwd": "/path/to/your/project" } } }

{ "mcpServers": { "supervisord-mcp": { "command": "uv", "args": ["run", "supervisord-mcp", "mcp"], "cwd": "/app" } } }

Note: This tool is designed for production and development environments using MCP's stdio transport method as specified in theMCP documentation. This approach provides secure, direct communication between AI agents and the process manager.

# 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

# 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

# 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

- 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

Supervisord's XML-RPC API has constraints for dynamic AI agent process management:

- add_processis 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 throwsALREADY_STARTEDerror (not idempotent)

For use cases where AI agents need to dynamically add and monitor processes,Circus MCPoffers a more complete API. Supervisord MCP is best suited for integrating with existing Supervisord environments.

# 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

# 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)

# Reload configuration after changes uv run supervisord-mcp reload

# 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

[unix_http_server] file=/tmp/supervisor.sock [supervisord] logfile=/tmp/supervisord.log logfile_maxbytes=50MB logfile_backups=10 loglevel=info pidfile=/tmp/supervisord.pid nodaemon=false minfds=1024 minprocs=200 [rpcinterface:supervisor] supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface [supervisorctl] serverurl=unix:///tmp/supervisor.sock [inet_http_server] port=127.0.0.1:9001 [include] files = /etc/supervisor/conf.d/.conf

supervisord -c /etc/supervisor/supervisord.conf

uv run supervisord-mcp --help uv run supervisord-mcp info

[program:webapp] command=gunicorn app:application --bind 0.0.0.0:8000 directory=/app numprocs=1 autostart=true autorestart=true startsecs=10 startretries=3 user=www-data redirect_stderr=true stdout_logfile=/var/log/webapp.log

# Use custom Supervisord server uv run supervisord-mcp --server-url http://localhost:9001/RPC2 list-processes

# 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

supervisorctl status # Step 1: Check all processes supervisorctl status webapp # Step 2: Check target → FATAL supervisorctl tail webapp stderr # Step 3: stderr logs (unbounded output risk) cat /var/log/supervisor/webapp-stderr.log | tail -50 # Step 4: Read log file directly supervisorctl start webapp # Step 5: Attempt restart sleep 2 && supervisorctl status webapp # Step 6: Check after restart supervisorctl tail webapp stderr | tail -20 # Step 7: Check logs again ps aux | grep webapp # Step 8: Verify process existence journalctl -u supervisor --no-pager -n 30 # Step 9: systemd logs cat /etc/supervisor/conf.d/webapp.conf # Step 10: Check configuration lsof -i :8080 # Step 11: Check port conflicts free -m # Step 12: Check resource exhaustion

list_processes # Spot FATAL immediately get_process_status("webapp") # Detailed status get_logs("webapp", lines=20, stderr=true) # Error logs (bounded to 20 lines) restart_process("webapp") # Restart get_process_status("webapp") # Verify after restart

MCP server for the Enoch control plane: dispatch gates, evidence sync, provenance, and quality gates for long-running autonomous AI work.