SupervisordMCP- AI Agent DevServer Management Made Simple

Supervisord MCP

Model Context Protocol（MCP）を通じてAIエージェントと連携し、Supervisordのプロセス管理を効率化します。

Supervisord MCPは、Model Context Protocolを通じてコーディングエージェントがSupervisordのプロセス管理に直接アクセスできるようにします。標準化されたプロセス制御機能を提供することで、シェルコマンドの解析に伴う複雑さを解消し、本番環境や開発環境で作業するAIエージェントのトークン消費を削減します。

MCP 統合シーケンス

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とは？

Supervisord MCPを使うと、AIコーディングエージェントは本番環境のプロセス管理をより効率的に行え、デプロイの信頼性と運用効率の向上につながります。

Supervisord MCPは、Model Context Protocolを通じてプロセスを直接制御し、シェルコマンドによるオーバーヘッドをなくして、本番環境や開発環境を管理するAIエージェントのトークン消費を削減します。

主な機能：

• AI連携：コーディングエージェント向けのMCPプロトコルを標準でサポート
• 本番環境対応：実績のあるSupervisordプロセスマネージャーを基盤にしています
• リアルタイム監視：プロセスのステータスとログにアクセスできます
• 堅牢な運用：プロセスのライフサイクルを確実に管理します

クイックスタート

インストール

uv add supervisord-mcp

基本的な使い方

# 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

🤖 AIエージェントとの連携

Supervisord MCPにはMCPプロトコルのサポートが組み込まれており、AIエージェントがプロセスを管理できます。

# Start MCP server for AI integration
uv run supervisord-mcp mcp

推奨されるstdioトランスポートを使用するよう、AIエージェントで設定します。

{
  "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"
    }
  }
}

注：このツールは、MCPドキュメントに記載されているMCPのstdioトランスポート方式を使用する、本番環境および開発環境向けに設計されています。この方式により、AIエージェントとプロセスマネージャー間の安全で直接的な通信が可能になります。

一般的なユースケース

本番環境のWebアプリケーション

# 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

Supervisord MCPを選ぶ理由

Circus MCPとの比較

• 本番環境を重視：Supervisordは本番環境向けに設計されています
• 安定性：長年にわたる本番環境での利用実績がある、十分に検証されたプロセススーパーバイザーです
• 設定：プロセスの定義には標準のsupervisord.confを使用します

注：AIエージェント連携に関する制約

SupervisordのXML-RPC APIには、AIエージェントによる動的なプロセス管理に関する制約があります。

• add_processはAPI経由ではサポートされていません（設定ファイルの手動編集とreloadが必要です）
• stdout/stderrのログを取得するには、個別にAPIを呼び出す必要があります
• API経由でCPU／メモリのリソース指標を取得できません
• すでに実行中のプロセスを起動すると、ALREADY_STARTEDエラーが発生します（冪等ではありません）

AIエージェントでプロセスを動的に追加・監視する必要があるユースケースには、より完全なAPIを提供するCircus MCPが適しています。Supervisord MCPは、既存のSupervisord環境との連携に最適です。

systemdとの比較

• クロスプラットフォーム：Pythonが動作するあらゆるシステムで使えます
• 使いやすさ：シンプルなコマンドとAI連携を提供します
• 柔軟性：設定とプロセス管理が簡単です

PM2との比較

• Pythonネイティブ：Pythonアプリケーションに最適です
• AI連携：MCPプロトコルを標準でサポートします
• 本番環境での実績：広く使われているSupervisordを基盤にしています

高度な機能

プロセス制御

# 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

インストールとセットアップ

システム要件

• Python 3.10以降
• Supervisordがインストールされ、実行中であること
• 任意のオペレーティングシステム（Linux、macOS、Windows）

インストール方法

# 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 のセットアップ

1. Supervisord をインストールします：

pip install supervisor

2. 設定ディレクトリを作成します：

mkdir -p /etc/supervisor/conf.d

3. メイン設定ファイル /etc/supervisor/supervisord.conf を作成します：

[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 MCP では、HTTP アクセスを有効にした [inet_http_server] 設定ブロックが必要です。このツールは HTTP XML-RPC プロトコル経由で Supervisord に接続し、Unix ドメインソケット接続には対応していません。

4. Supervisord を起動します：

supervisord -c /etc/supervisor/supervisord.conf

インストールの確認

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

設定

Supervisord MCP は標準の Supervisord 設定で動作します。プログラムを /etc/supervisor/conf.d/ に追加してください：

プログラム設定の例

[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

カスタムサーバー URL

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

利用可能な MCP ツール

AI エージェントでは、以下のツールを利用できます：

• add_process：新しいプロセスを追加します（設定の再読み込みが必要です）
• start_process：プロセスを起動します
• stop_process：プロセスを停止します
• restart_process：プロセスを再起動します
• list_processes：すべてのプロセスを一覧表示します
• get_process_status：プロセスの詳細なステータスを取得します
• get_logs：プロセスのログ（stdout/stderr）を取得します
• get_system_info：Supervisord のシステム情報を取得します
• reload_config：Supervisord の設定を再読み込みします

ヘルプ

ドキュメント

• Supervisord ドキュメント - Supervisord の公式ドキュメント
• MCP ドキュメント - Model Context Protocol の仕様

サポート

• GitHub Issues：バグの報告や機能のリクエスト
• ディスカッション：コミュニティに参加

コマンド早見表

# 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

AI エージェントのトークンコスト分析

トークンを削減すれば、エージェントはより速く動作します。 AI エージェントがプロセスの監視に費やすトークンは、実際の問題解決に使われないトークンです。調査によると、エージェント型ワークフローでは、反復的なデバッグ段階でトークン全体の最大59.4％が消費されます（Tokenomics, 2026）。MCP を通じて構造化された簡潔な応答を提供することで、AI を活用したデバッグの最大のコスト要因である、不要な往復と構造化されていない出力の解析を削減できます。

ツールスキーマのオーバーヘッド（コンテキスト常駐コスト）

MCP ツールを登録すると、そのスキーマ定義はセッション中、会話コンテキストに保持されます。

項目	推定トークン数
9 個のツールスキーマ	~1,100 トークン

呼び出しごとのトークンコスト

操作	リクエスト	応答	合計
list_processes（5 個のプロセス）	~30	~120-200	~150-230
get_process_status	~40	~100-150	~140-190
get_logs（10 行）	~50	~150-450	~200-500
get_logs（50 行）	~50	~750-2,450	~800-2,500
get_logs（100 行、デフォルト）	~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 と Linux コマンドの比較 —「即終了」調査

起動直後に終了するプロセスをデバッグする場合のコスト比較です。

生のコマンド（MCP なし）：12 ステップ

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

• Bash の呼び出しごとに、固定のオーバーヘッドとして約60～90トークンが発生します
• supervisorctl tail には行数制限がないため、トークンが急増するリスクがあります
• 構造化されていないテキスト出力により、LLM の解析エラーが発生します
• 各ステップの間に推論トークンが消費されます（1 ステップあたり約150～250トークン）
• 「即終了」の場合、通常、この一連の手順を2～3 回繰り返す必要があります

MCP（構造化ツール）：5 ステップ

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	削減率
ツール呼び出し回数	8-12	3-5	60-70%
出力トークン数	2,000-8,500	560-1,160	70-85%
推論トークン数（ステップ間）	~1,500-3,000	~500-1,000	60-70%
合計トークン数（スキーマを除く）	2,900-9,400	935-1,535	60-85%
合計トークン数（スキーマを含む）	2,900-9,400	2,035-2,635	30-70%
ラウンドトリップ数	8-12	3-5	60%
経過時間	12-36s	~5s	60-85%
パースの信頼性	低（非構造化）	高（構造化）	—

リトライ時のスケーリング

調査の繰り返しが必要な場合の累積コスト（「すぐに終了する」問題でよく発生します）：

リトライ回数	生コマンド	MCP	削減率
1回（成功）	~2,900-9,400	~935-1,535	60-85%
2ループ	~5,000-15,000	~1,500-2,500	70-83%
3ループ	~7,000-20,000	~2,000-3,500	71-82%

生コマンドのコストはリトライのたびに指数関数的に増加します（調査用コマンドが蓄積するため）が、MCP のコストは線形に増加します。

損益分岐点：スキーマの常駐コスト（約1,100トークン）を考慮すると、MCP は3～4回のツール呼び出しでコストが同等になり、それを超えるとコストが低くなります。

最適化のヒント

ヒント	効果
get_logs の lines=10~20 に制限する	ログ取得コストを70～80%削減
概要の確認には list_processes を1回だけ使用する	個別のステータス確認が不要になります
stderr のみを取得するには stderr=true を使用する	stdout にトークンを浪費するのを防ぎます
ステータス確認のみの場合は get_system_info を省略する	約80～120トークンを節約できます

参考資料

このトークンコスト分析の根拠となった研究：

• Tokenomics: Quantifying Where Tokens Are Used in Agentic SE — エージェント型ワークフローにおけるトークン消費の初の実証分析です。反復段階でトークンの59.4%が消費されます
• Help or Hurdle? Rethinking MCP-Augmented LLMs — MCPGAUGE：オーバーヘッドを含む4つの観点から評価する、初のMCP評価フレームワークです
• MCP Tool Descriptions Are Smelly! — 856個のツール／103個のMCP サーバーを対象とした大規模調査です。ツールの説明の品質は、エージェントの効率に直接影響します
• MCPAgentBench — 841個のタスク、20,000個を超えるMCP ツールを対象とするベンチマークです。評価指標としてトークン効率（TEFS）を定義しています
• AgentDiet: Trajectory Reduction — 入力トークンを39.9～59.7%削減します
• Token-Budget-Aware LLM Reasoning — 出力トークンを67%、コストを59%削減します
• Token Efficiency with Structured Output — 関数呼び出しは最もトークン効率の高い出力形式です（Microsoft）

ライセンス

MIT License — 詳細は LICENSE をご覧ください。

作者について

AetherPlatform — クラウドネイティブ開発ツールの未来を築いています

• GitHub：@aether-platform
• プロジェクトのウェブサイト：AetherPlatform
• お問い合わせ：[email protected]

ミッション

AI 統合と最新のクラウドネイティブ技術を通じて、開発者の生産性を高めるツールを開発しています。Supervisord MCP は、ソフトウェア開発ライフサイクルの効率化を目的とした、開発ツールの幅広いエコシステムの一部です。

その他のプロジェクト

• AetherSaaS：SaaS プラットフォーム管理コンソール
• AetherCoding：AI で強化された開発環境
• AetherOperation：運用およびターミナル管理ツール
• Circus MCP：Circus による代替プロセス管理

謝辞

堅牢で信頼性の高いプロセス管理基盤を開発してくださった**Supervisord**開発チームに、心より感謝申し上げます。皆さまの素晴らしい取り組みがあったからこそ、このプロジェクトを実現できました。Supervisord MCPは、確かなアーキテクチャを基盤として、プロセス管理に最新のAIエージェント連携をもたらします。

関連プロジェクト

• Supervisord - 基盤となるプロセスマネージャー
• Model Context Protocol - AIエージェントの通信規格
• AetherPlatform - クラウドネイティブな開発ツール
• Circus MCP - 代替のプロセス管理ソリューション

---

❤️を込めて、AetherPlatformが制作

Supervisord MCP：本番環境対応のプロセス管理と、AIを活用した自動化。