Agentic Team MCP — Persistent Multi-Agent Orchestration for Model Context Protocol

Live interactive Web Studio floor visualization showing Root Watchdog supervision, hierarchical reporting trees, and dynamic agent collaboration links. (See animated preview: assets/web_studio_preview.gif)

Agentic Team MCP is an enterprise-grade, local-first multi-agent orchestration platform designed around the Model Context Protocol (MCP). It establishes a persistent, hierarchical agent workforce (Root Watchdog Supervisor → CEO Strategy → Manager Execution → Specialist Workers) that bridges native CLI coding environments (Claude Code, Gemini Antigravity, Codex) with unified direct API providers (DeepSeek, Z.ai/GLM, Google Gemini, OpenAI, and OpenRouter).

🌟 What's New in v0.3.0

• 🔀 Smart Flank Bezier Routing & Floor Clearance:

  • Non-Intersecting Trajectories: CEO-to-Worker communication conduits now calculate dynamic cubic Bezier flanking curves around Manager nodes, eliminating line occlusion.

  • Optimized Vertical Clearance: Auto-arrange engine now spaces Manager at $y=295$ and Workers staggered at $y=580$, giving ample clearance for high-density multi-agent trees.

  • Directional Transmission Animations: Real-time .active-comm conduits stream directional animated glowing pulse orbs indicating exact source-to-target payload transfer.

• ⚡ Two-Line Responsive KV Caching Telemetry:

  • Redesigned .caching-chip badges into two responsive tiers (⚡ KV Cache / 86.4% · 128k hit), preventing truncation on mobile viewports and compact agent cards.

• 🛡️ Zero-Interference Multi-Account Quota Isolation:

  • Independent account error boundaries in core/auth_pool.py: rate limits or 429 quota exhaustion on an individual Google profile never block or contaminate other healthy accounts in the pool.

  • Instant Live Self-Healing: Cooldown states are immediately revoked and restored to HEALTHY upon verified successful turn execution, with automated background cleanup for expired windows.

• 📱 Telegram Mobile Supervisor Hardening:

  • Telemetric desktop screenshot capture hardened against prompt swallowing during high-load periods.

  • Persistent per-chat project session memory and live /project switching for autonomous remote orchestration.

Related MCP server: MEMGRAPH-MCP

Author's Note

Abdulaziz Komilov (@menma4ever), student researcher in local model fine-tuning and quantization, building persistent, cost-effective multi-agent teams across native CLIs (Claude Code, Gemini Antigravity, Codex) and Model Context Protocol.

Modern agent frameworks often suffer from three fatal flaws: fragile ephemeral execution contexts, proprietary cloud lock-in, and ballooning API token costs. Agentic Team MCP was engineered to solve these problems by coupling persistent SQLite event sourcing with native CLI adapters (leveraging existing subscription authorizations like Claude Code, Gemini Antigravity, and Codex CLI) alongside high-efficiency open-weights models (DeepSeek-V3/R1 and GLM-5). The result is an autonomous, self-healing team architecture capable of executing complex engineering milestones locally, deterministically, and cost-effectively.

Visual Architecture

flowchart TD
    subgraph ClientLayer["User & Client Layer"]
        User["Developer / User"]
        ClaudeDesktop["Claude Desktop"]
        CursorIDE["Cursor IDE"]
        WebBrowser["Web Browser (Studio GUI)"]
        TelegramUser["Telegram Mobile Client"]
    end

    subgraph GatewayLayer["MCP & Gateway Layer"]
        MCPServer["FastMCP Stdio Server<br/>(mcp_server/server.py)"]
        WebStudio["Web Studio & REST Gateway<br/>(FastAPI / Uvicorn)"]
        TelegramBridge["Telegram Supervisor Bridge<br/>(core/telegram_bridge.py)"]
    end

    subgraph CoreLayer["Orchestrator Core"]
        Engine["Orchestrator Engine<br/>(engine/orchestrator.py)"]
        SQLiteStore["SQLite Event Sourcing<br/>(team.sqlite3)"]
        Queues["Task Queues & Loop Monitor"]
        WatchdogBrain["Watchdog Supervisor Engine<br/>(core/watchdog_brain.py)"]
    end

    subgraph TeamHierarchy["Hierarchical Agent Team"]
        Watchdog["Root Watchdog Agent<br/>(Global Supervisor & Bridge)"]
        CEO["CEO Agent<br/>(Strategic Planning & Architecture)"]
        Manager["Manager Agent<br/>(Milestone Breakdown & Task Dispatch)"]
        Worker1["Specialist Worker 1<br/>(Implementation / Code)"]
        Worker2["Specialist Worker 2<br/>(Documentation / QA)"]
    end

    subgraph ExecutionLayer["Execution Harnesses & Providers"]
        subgraph CLIAdapters["Native CLI Harnesses"]
            ClaudeCode["Claude Code CLI"]
            AntigravityCLI["Gemini Antigravity CLI"]
            CodexCLI["Codex CLI"]
            HermesCLI["Hermes / OpenClaw"]
        end
        subgraph DirectAPI["Direct API Providers"]
            DeepSeekAPI["DeepSeek (V3 / R1)"]
            ZaiAPI["Z.ai / GLM-5"]
            GeminiAPI["Google Gemini"]
            OpenAIAPI["OpenAI"]
            OpenRouterAPI["OpenRouter / SiliconFlow / Groq"]
        end
    end

    User --> ClaudeDesktop
    User --> CursorIDE
    User --> WebBrowser
    TelegramUser <--> TelegramBridge

    ClaudeDesktop -->|"stdio MCP"| MCPServer
    CursorIDE -->|"stdio MCP"| MCPServer
    WebBrowser -->|"HTTP / WebSocket"| WebStudio
    TelegramBridge <--> WatchdogBrain

    MCPServer -->|"Engine Actions"| Engine
    WebStudio -->|"REST / Event Streams"| Engine
    WatchdogBrain <--> Engine

    Engine <--> SQLiteStore
    Engine <--> Queues

    Watchdog -.->|"Supervises"| CEO
    Watchdog -.->|"Supervises"| Manager
    Engine --> CEO
    CEO -->|"Dispatches Roadmap"| Manager
    Manager -->|"Assigns Task"| Worker1
    Manager -->|"Assigns Task"| Worker2

    Worker1 --> CLIAdapters
    Worker2 --> DirectAPI

Why Agentic Team MCP?

Key Architectural Capabilities

1. Persistent Multi-Agent State & Event Sourcing

Unlike ephemeral agent systems that lose all state on reload, Agentic Team MCP records all state mutations, messages, agent definitions, and task outcomes in an event-sourced SQLite database (team.sqlite3). If your system reboots, the engine reconstitutes the full agent graph and automatically resumes pending assignments.

2. Multi-Account Google Auth Pool (core/auth_pool.py)

• Directory Isolation: Per-account directory sandboxes (auth/google/account_XX/) with separate credential vaults.

• Windows Keyring Vault Swap: Automated backup and capture of active tokens preventing profile contamination on Windows.

• Sticky KV-Cache Affinity: Grants agents slot affinity (forced_auth_slot_id) to maximize prompt cache hits.

• Automatic 429 Quota Failover: Detects rate limits or token saturation and fails over to healthy slots seamlessly.

3. Multi-Harness Subsystem (harness/)

• Native CLI Subprocess Runners: Directly leverages your active terminal subscriptions (agy, codex, claude) in headless mode without per-token charges.

• High-Throughput Direct API Client: Async SSE streaming client supporting DeepSeek-V3/R1, Zhipu GLM, OpenAI, Experiential Labs (xpl), and Groq.

• Context Preservation & Handoffs: Automatically serializes transcripts on model/harness switches (manager/.handoffs/<hash>.json) to prevent cognitive amnesia.

4. Root Watchdog & Autonomous Telegram Bridge (core/telegram_*)

• Always-on Mobile Supervision: Connect via Telegram (@ufljarvisbot) with strict chat ID whitelisting (5644286697).

• Human-like UX: 4.5s typing simulation loop, mobile-first formatting, and automated [DISPATCH] & [SEND_FILE] directives.

• Multimodal Ingestion (core/multimodal.py): Audio voice notes are transcribed via speech-to-text; images and PDFs are converted to native vision tokens.

5. Real-Time Web Studio GUI (web/)

• Full-Screen Team Floor: Interactive node-link canvas showing agent states (idle, working, resting, failed). Click the fullscreen icon to expand the floor to the entire display.

• Live SVG Message Vectors: Real-time traveling pulses along SVG vectors whenever agents exchange messages or report results.

• Comprehensive Telemetry: Granular dashboards tracking input_tokens, output_tokens, cache_read_tokens, and provider burn in real time.

6. Granular Security Boundary

• Strict Workspace Sandboxing: Specialist workers operate strictly within their assigned project directories (workers/<name>/).

• Automatic Key Redaction: Zero-secret leakage policy regex-redacts sensitive API keys and tokens across console streams and log files.

2-Minute Quickstart Guide

Prerequisites

• Python 3.11+ installed and available on your system PATH.

• Git installed.

• (Optional) Installed CLI tools: claude (Claude Code), agy (Antigravity CLI), or codex (OpenAI Codex).

Step 1: Installation & Setup

Windows (One-Click Setup)

Clone the repository and run the automated PowerShell setup script:

git clone https://github.com/menma4ever/agentic-team-mcp.git
cd agentic-team-mcp
.\Setup.ps1

Manual Virtual Environment Setup (Cross-Platform)

# 1. Clone the repository
git clone https://github.com/menma4ever/agentic-team-mcp.git
cd agentic-team-mcp

# 2. Create and activate a Python virtual environment
python -m venv .venv

# On Windows (PowerShell):
.venv\Scripts\Activate.ps1
# On Linux / macOS:
source .venv/bin/activate

# 3. Install core dependencies
pip install -r requirements.txt

Step 2: Configuration

Copy the clean example settings template to settings.json:

cp settings.example.json settings.json

Edit settings.json with your preferred API keys or enable local CLI harnesses:

{
  "api_keys": {
    "deepseek": "sk-your-deepseek-key",
    "zai": "your-zai-api-key",
    "gemini": "your-gemini-api-key",
    "openai": "",
    "anthropic": ""
  },
  "cli_auth_enabled": {
    "claude": true,
    "agy": true,
    "codex": false
  }
}

Step 3: Launching the Platform

Launch Web Studio & Orchestrator Engine

On Windows, simply double-click Launch.cmd or run:

Launch.cmd

Alternatively, from an activated virtual environment:

python main.py

This automatically boots the background orchestrator service, launches the Web Studio GUI, and opens your default browser at http://127.0.0.1:8765/#token=<token>.

Available Command-Line Arguments

python main.py [OPTIONS]

Options:
  --port INTEGER    Port for web studio & engine (default: 8765)
  --no-browser      Start engine and studio without opening browser
  --mcp             Run as stdio Model Context Protocol (MCP) server
  --console TEXT    Open human-in-the-loop interactive console for agent

Step 4: Connecting to MCP Clients

Agentic Team MCP operates as a high-performance stdio MCP server that connects directly to your background engine.

Claude Desktop Configuration

Add the server definition to your claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "agentic-team": {
      "command": "C:\\path\\to\\agentic-team-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\agentic-team-mcp\\main.py",
        "--mcp"
      ]
    }
  }
}

Cursor IDE Configuration

Add the configuration to .cursor/mcp.json in your workspace or global Cursor settings:

{
  "mcpServers": {
    "agentic-team": {
      "command": "C:\\path\\to\\agentic-team-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\agentic-team-mcp\\main.py",
        "--mcp"
      ]
    }
  }
}

Available MCP Tools Reference

When connected via MCP, Agentic Team exposes a comprehensive set of orchestration tools:

Directory Structure

agentic-team-mcp/
├── assets/                  # Studio screenshots & preview assets
│   ├── web_studio_team_floor.png
│   ├── web_studio_preview.gif
│   └── web_studio_overview.png
├── Launch.cmd               # Fast Windows launcher
├── Setup.ps1                # Automated PowerShell virtualenv & dependency setup
├── LICENSE                  # MIT License
├── README.md                # Project documentation & guides
├── requirements.txt         # Core dependencies
├── settings.example.json    # Example configuration template
├── main.py                  # Main entry point (Web Studio, Engine & MCP Server)
├── core/                    # Core supervisor, telegram bridge, auth pool & config
│   ├── auth_pool.py         # Multi-account rotation & CLI auth slots
│   ├── catalog.py           # Dynamic model & harness discovery
│   ├── config.py            # Pydantic schema validation & redaction
│   ├── credential_store.py  # Secure local credential storage
│   ├── multimodal.py        # Visual analysis & image processing
│   ├── service.py           # Engine lifecycle & process locking
│   ├── telegram_bridge.py   # Telegram supervisor bridge & alert loop
│   ├── telegram_supervisor.py # Interactive mobile control endpoints
│   ├── watchdog_brain.py    # Root Watchdog intelligence & evaluation
│   └── workspace.py         # Sandboxed workspace directories
├── engine/                  # Orchestration core & persistence
│   ├── actions.py           # Agent action handlers & dispatching
│   ├── loop_monitor.py      # Stuck-loop detection & runaway turn prevention
│   ├── message_router.py    # Priority messaging & event routing
│   ├── models.py            # Pydantic data models for agents & tasks
│   ├── orchestrator.py      # Central event loop & agent scheduler
│   └── store.py             # SQLite event-sourcing database layer
├── harness/                 # Subprocess & provider execution harnesses
│   ├── cli_runner.py        # PTY/pipe adapters for Claude, Antigravity, Codex
│   └── direct_api.py        # Direct async streaming HTTP API client
├── mcp_server/              # Model Context Protocol stdio server
│   └── server.py            # FastMCP tool declarations & engine proxy
├── tests/                   # End-to-end integration & unit test suites
│   ├── test_auth_pool.py
│   ├── test_backend_audit.py
│   ├── test_engine.py
│   ├── test_google_quota_recovery.py
│   ├── test_release.py
│   ├── test_runtime_revision.py
│   ├── test_service.py
│   ├── test_telegram_bridge.py
│   └── test_watchdog_brain.py
└── web/                     # Web Studio dashboard & REST API
    ├── app.py               # FastAPI server & WebSocket endpoints
    └── static/              # Interactive graph, terminal streams, and UI

Community & Feedback

We welcome contributions, feedback, and questions from researchers and builders working on autonomous multi-agent systems and MCP tooling.

• Telegram: @zwyci / Bot: @ufljarvisbot

• Discord: 77terminator77

• GitHub Issues: menma4ever/agentic-team-mcp/issues

• GitHub Discussions: menma4ever/agentic-team-mcp/discussions

License

Distributed under the MIT License. See LICENSE for complete terms.