Circus

PyPI version Python 3.10+ License: MIT

Cut 75-80% of AI agent debugging tokens in development cycle. Process management via MCP — structured tools replace shell commands.

75-80% Token Reduction for AI Agent Debugging in Development Cycle

AI agents debugging processes via raw shell commands (supervisorctl, ps, journalctl) burn most of their tokens on unstructured output parsing, repeated commands, and inter-step reasoning. Circus MCP replaces this with structured, bounded MCP tool responses.

	Raw Commands	Circus MCP	Reduction
Tool calls per investigation	8-12	3-5	60-70%
Tokens per investigation	2,900-9,400	935-1,535	~75%
With retries (typical)	~10,000+	~2,000	~80%
Retry cost scaling	Exponential	Linear	—

Process Management via MCP

Circus MCP exposes process lifecycle operations as MCP tools. AI agents call structured tools instead of parsing shell output.

Tool	Parameters	Description
list_processes	—	List all managed processes
get_process_status	name	Process state and PID
start_process	name	Start a process
stop_process	name	Stop a process
restart_process	name	Restart a process
add_process	name, command, numprocesses?, working_dir?	Add a new process dynamically

Claude Code

claude mcp add circus-mcp -- uv run circus-mcp mcp

VS Code / Cursor

.vscode/mcp.json:

{
  "servers": {
    "circus-mcp": {
      "command": "uv",
      "args": ["run", "circus-mcp", "mcp"]
    }
  }
}

Circus MCP vs Supervisord MCP

	Circus MCP	Supervisord MCP
Dynamic process addition	Via API	Not supported (requires config file edit + reload)
Log retrieval	stdout + stderr in one call	Separate calls
System stats (CPU/memory)	Available	Not available
Idempotent operations	ensure_started / ensure_stopped	Throws error if already running
Transport	ZeroMQ (async)	HTTP XML-RPC (sync)
Best for	AI agent workflows	Existing Supervisord environments

Documentation

• AI Token Reduction Solution — Token cost analysis, team-scale projections, research references
• AI & MCP Technical Background — Architecture, MCP hosting, tenant isolation
• Installation & CLI Reference — Setup, configuration, full command reference

License

MIT — see LICENSE. Built on Circus.