← All Diagrams
An MCP server on port 7891 allows external AI clients (Claude Code, etc.) to spawn background agent tasks
and collect results. Non-blocking design: callers start agents, do other work, then poll/wait for results.
Session state is persisted to disk so callers can resume conversations across separate run_agent calls.
MCP Client
Claude Code / any MCP client
Authorization: Bearer {token}
vibex-subagents MCP :7891
mcp_server.py · FastMCP("vibex-subagents", stateless_http=True)
Bearer auth · Rate limit (120/min/token) · Session persistence
Task TTL: 1 hour · mcp_sessions.json for cross-call resume
run_agent
Spawn background asyncio task
prompt (required) · backend (claude/codex/gemini)
project_dir · model · session_id (resume)
isolation: "worktree" for git branch isolation
→ Returns {task_id, session_id, status:"running"}
agent_result
Poll / wait / cancel / logs / list
task_ids (single or list) · action (default: poll)
wait_secs (0-300) · return_completed (bool)
cancel: SIGTERM · logs: stderr output
→ {status, output, tokens_remaining_pct, files}
sessions
Session + server management
session_id · action: list/delete/reset/list-all
list-all: server info + all sessions + usage
reset: clear context, get new session_id
→ {sessions[], server_info, uptime}
TASK LIFECYCLE
queued
running
completed
failed
cleaned (1h)
# Typical workflow — single agent: 1. run_agent (prompt="refactor auth module" , backend="claude" , project_dir="/path/to/repo" , model="opus" )"abc123" , session_id: "sess-xyz" , status: "running" }2. agent_result (task_ids="abc123" , wait_secs=60 )"completed" , output: "Refactored auth..." , tokens_remaining_pct: 72.5 }# Parallel execution — multiple agents: 1. t1 = run_agent (prompt="write unit tests" , backend="codex" )2. t2 = run_agent (prompt="review for security issues" , backend="gemini" )3. agent_result (task_ids=[t1.task_id, t2.task_id], return_completed=True)# Session management: 3. If tokens_remaining_pct < 10%: sessions (session_id="sess-xyz" , action="reset" ) → {new_session_id: "sess-new" }# Worktree isolation: run_agent (prompt="experimental change" , isolation="worktree" )