⚡ MCP Agent Orchestrator

An open, extensible Model Context Protocol (MCP) server that acts as a scalable, multi-modal multi-agent coordination engine.

It allows any MCP-compatible client (Claude Desktop, Cursor, Antigravity, Zed, LibreChat) to delegate complex multi-step programming and research goals to internal teams of specialized subagents — acting as a context firewall to conserve client token limits while preventing tool timeouts.

🌟 Key Features

• 🧠 Multi-Modal Orchestration:
  1. Cross-Session Agent Mesh (invoke_session, send_session_message, check_inbox): Spawn independent specialist subagents in isolated sessions with dedicated models, context boundaries, persistent SQLite inboxes, and bidirectional inter-session messaging.
  2. Autonomous Swarm (start_swarm): Supervisor agent decomposes goals into subtasks, delegates to worker agents, and synthesizes final outputs.
  3. Interactive Toolkit (spawn_agent, send_agent_message): Direct agent management primitives enabling host models to orchestrate custom loops.
  4. Structured Pipelines (run_pipeline): Deterministic multi-stage DAG workflows passing typed artifacts with human-in-the-loop checkpoints (approve_checkpoint).
• 🔌 Flexible Inference (Zero API Keys or Cloud APIs):
  • Zero-Key Local Setup: Uses your authenticated local Antigravity (agy) CLI (accessing gemini-3.8-flash-high, claude-sonnet-4-6, etc.) or Ollama.
  • Cloud API Setup: Direct integrations for Google Gemini, Anthropic, OpenAI, or any OpenAI-compatible provider (DeepSeek, Groq, Together).
  • Hybrid Setup: Mix and match free local models for high-volume workers and cloud frontier models for critical reviews.
• 🛡️ Sandboxed Workspace Tools:
  • Scoped filesystem tools (fs_read, fs_write, fs_list, fs_delete).
  • Controlled shell execution (shell_exec) with configurable safety modes (autonomous, semi-autonomous, safe).
  • Web search and HTTP fetch (web_fetch).
  • MCP Gateway Bridge: Subagents can dynamically call tools on third-party MCP servers (e.g. GitHub, PostgreSQL, Docker).
• 💾 State & Persistence:
  • Embedded SQLite database (data/orchestrator.db) with WAL mode.
  • Persists task histories, agent thought transcripts, and generated artifacts across restarts.
• 🖥️ Live Web Dashboard:
  • Runs on http://localhost:4000 with Server-Sent Events (SSE).
  • Real-time progress tracker, live agent scratchpads, artifact previewer, and one-click checkpoint approval buttons.

🏗️ Architecture

flowchart TD
    Client["Host MCP Client\n(Claude Desktop / Cursor / Antigravity / Zed)"]

    subgraph Server["MCP Agent Orchestrator Server"]
        subgraph Transport["MCP Protocol Layer (stdio)"]
            Tools["MCP Tools\n(start_swarm, run_pipeline, spawn_agent, etc.)"]
            Status["Inspection Tools\n(get_task_status, list_jobs, approve_checkpoint)"]
        end

        subgraph Kernel["Orchestration Kernel"]
            Dispatcher["Task Dispatcher & Scheduler"]
            PolicyEngine["Workspace & Safety Policy Gatekeeper"]
            Supervisor["Swarm Supervisor"]
            DAGRunner["Pipeline DAG Runner"]
            AgentPool["Interactive Agent Pool"]
        end

        subgraph Inference["Inference Layer"]
            Agy["Local agy CLI\n(Zero Keys)"]
            Ollama["Local Ollama\n(Zero Keys)"]
            Cloud["Cloud APIs\n(Gemini / Anthropic / OpenAI / DeepSeek)"]
        end

        subgraph Capabilities["Subagent Capabilities"]
            Builtins["Workspace Tools\n(fs, shell, web)"]
            Bridge["MCP Bridge\n(External MCP Servers)"]
        end

        subgraph Persistence["Storage & Dashboard"]
            DB[("SQLite Storage\n(data/orchestrator.db)")]
            UI["Web Dashboard\n(http://localhost:4000)"]
        end
    end

    Client <-->|"stdio"| Transport
    Transport --> Dispatcher
    Dispatcher --> PolicyEngine
    PolicyEngine --> Supervisor & DAGRunner & AgentPool
    Supervisor & DAGRunner & AgentPool --> Inference
    Supervisor & DAGRunner & AgentPool <--> Capabilities
    Dispatcher <--> DB
    DB <--> UI

⚡ Quick Start & CLI

1. Instant Run with uvx / pip (PyPI)

# Run directly via uvx (zero install) or install from PyPI
uvx session-mesh-mcp doctor
pip install session-mesh-mcp

# Start the MCP server over stdio
session-mesh-mcp serve

# Launch the live Web Dashboard on http://localhost:4000
session-mesh-mcp dashboard

2. Instant Run with npx (Node.js)

# Run the built-in system diagnostics & health check
npx agent-mesh-mcp doctor

# Generate a starter orchestrator.yaml in your current directory
npx agent-mesh-mcp init

# Start the MCP server over stdio
npx agent-mesh-mcp

3. Local Development & Build

git clone https://github.com/ShashankIIITN/agent-mesh-mcp.git
cd agent-mesh-mcp

# Install dependencies and compile TypeScript
npm install
npm run build

# Run all 14 unit and integration tests
npm test

⚙️ Configuration (orchestrator.yaml)

Create orchestrator.yaml in the project root (you can also reference orchestrator.example.yaml):

version: "1.0"

server:
  port: 4000 # Web Dashboard port (http://localhost:4000)
  storage:
    type: "sqlite"
    connection_string: "./data/orchestrator.db"
  security:
    default_safety_mode: "semi-autonomous" # autonomous | semi-autonomous | safe
    allowed_workspaces:
      - "./"
      - "D:/"

# ─────────────────────────────────────────────────────────────────────────
# INFERENCE PROVIDERS
# Choose your setup: Local (Zero API Keys), Cloud API Keys, or Hybrid
# ─────────────────────────────────────────────────────────────────────────
inference:
  default_provider: "direct"
  # Cost & capability tiers for isolated child sessions
  tiers:
    fast:
      provider: "agy"
      model: "gemini-3.8-flash-low" # Ultra-fast, zero thinking-token overhead
    balanced:
      provider: "agy"
      model: "gemini-3.8-flash-high"
    heavy:
      provider: "agy_claude"
      model: "claude-sonnet-4-6"
  providers:

    # ── Option A: Local Antigravity CLI (Zero API Keys) ──
    # Auto-detected on Windows, macOS, and Linux!
    agy:
      type: "agy"
      model: "gemini-3.8-flash-high" # Or "claude-sonnet-4-6", "gemini-3.1-pro-high"

    # ── Option B: Local Ollama (Zero API Keys) ──
    ollama:
      type: "ollama"
      base_url: "http://localhost:11434"
      model: "llama3.3"

    # ── Option C: Cloud API Providers (Require API Keys) ──
    gemini:
      type: "gemini"
      model: "gemini-2.5-flash"
      api_key_env: "GEMINI_API_KEY"

    anthropic:
      type: "anthropic"
      model: "claude-3-7-sonnet-20250219"
      api_key_env: "ANTHROPIC_API_KEY"

    openai:
      type: "openai"
      model: "gpt-4o"
      api_key_env: "OPENAI_API_KEY"

    # ── Option D: Custom OpenAI-Compatible (DeepSeek, Groq, Together) ──
    deepseek:
      type: "openai-compatible"
      base_url: "https://api.deepseek.com"
      model: "deepseek-coder"
      api_key_env: "DEEPSEEK_API_KEY"

# ─────────────────────────────────────────────────────────────────────────
# DECLARATIVE AGENT PERSONAS
# Assign each agent whichever provider you prefer (local or cloud)
# ─────────────────────────────────────────────────────────────────────────
agents:
  researcher:
    role: "Research & Documentation Specialist"
    provider: "agy" # Using zero-key local model
    tools: ["web_fetch", "fs_read", "fs_list"]
    system_prompt: "You are an expert researcher. Synthesize concise and factual summaries."

  coder:
    role: "Senior Software Engineer"
    provider: "agy"
    tools: ["fs_read", "fs_write", "fs_list", "shell_exec"]
    system_prompt: "You are a senior engineer. Write clean, robust code and verify changes."

  reviewer:
    role: "Staff Security & QA Auditor"
    provider: "agy"
    tools: ["fs_read", "fs_list", "shell_exec"]
    system_prompt: "You are a staff reviewer focused on correctness, edge cases, and security."

# ─────────────────────────────────────────────────────────────────────────
# PRESET PIPELINES
# ─────────────────────────────────────────────────────────────────────────
pipelines:
  feature_implementation:
    stages:
      - name: "research"
        agent: "researcher"
        output_artifact: "research_notes.md"
        checkpoint: false
      - name: "code"
        agent: "coder"
        input_artifacts: ["research_notes.md"]
        output_artifact: "implementation.md"
        checkpoint: true # Pauses for human approval
      - name: "review"
        agent: "reviewer"
        input_artifacts: ["implementation.md"]
        checkpoint: false

# ─────────────────────────────────────────────────────────────────────────
# EXTERNAL MCP GATEWAYS (Optional)
# Subagents can call tools from these external servers
# ─────────────────────────────────────────────────────────────────────────
mcp_gateways:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"

🔌 Connecting to Your MCP Client

You can connect either via npx (instant, portable) or pointing directly to your local clone.

1. Antigravity (agy)

To register the orchestrator globally in your local Antigravity environment:

# Using npx (portable):
agy mcp add agent-orchestrator npx -y mcp-agent-orchestrator

# OR using local build:
agy mcp add agent-orchestrator node "D:\my project\mcp-agent-orchestrator\dist\index.js" "D:\my project\mcp-agent-orchestrator\orchestrator.yaml"

Verify it is active:

agy mcp list

2. Claude Desktop

Add to your %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "agent-orchestrator": {
      "command": "npx",
      "args": ["-y", "mcp-agent-orchestrator"]
    }
  }
}

(Or replace "command": "node" and point to "D:\\my project\\mcp-agent-orchestrator\\dist\\index.js" for local development).

3. Cursor

1. Open Cursor Settings $\rightarrow$ Features $\rightarrow$ MCP Servers.
2. Click Add New MCP Server:
   • Name: agent-orchestrator
   • Type: command
   • Command:

     npx -y mcp-agent-orchestrator
     

     (Or node "D:\my project\mcp-agent-orchestrator\dist\index.js")

🛠️ MCP Tool Reference

Cross-Session Agent Mesh Tools (v0.2.0)

Swarm, Pipeline & Interactive Tools

🤖 Autonomous Agent Prompt (GEMINI.md / CLAUDE.md)

To let Gemini (Antigravity / Gemini CLI) or Claude (Claude Code / Claude Desktop) use the Multi-Context & Model-Tiered Session Mesh autonomously without manual prompting, copy GEMINI.md into ~/.gemini/GEMINI.md or CLAUDE.md into ~/.claude/CLAUDE.md (or your project root):

# 🌐 Autonomous Multi-Context & Model-Tiered Session Mesh Protocol (`agent-orchestrator`)

You are connected to the `agent-orchestrator` MCP server, which gives you the ability to spin up
**isolated AI sessions with separate context windows** and **custom model/cost tiers** (`fast`, `balanced`, `heavy`).

Use this Session Mesh **autonomously and proactively** without waiting for the user to ask you to spawn sessions.

## 🧠 Core Operating Principles

### 1. The Context Firewall Rule (Multiply Your Context Window)
- **Protect your primary context window**: Do NOT dump large file explorations (>3 files), noisy test/build logs, or bulk codebase scans into your main context window.
- **Offload to isolated sub-sessions**: Spin up a child session (`invoke_session` or `invoke_sessions_parallel`). Each spawned session runs in its **own fresh context window**, performs up to 20 tool-use iterations internally, and returns only a **distilled, high-signal summary** to your main session.
- **Reuse warm child contexts**: When you have follow-up questions about code a child session already read, call `send_session_message` with `target_session_id`—it resumes the child's persistent conversation context (`--conversation`) with prompt caching instead of re-reading files from scratch.

### 2. Cost & Capability Model Tiering (`tier: "fast" | "balanced" | "heavy"`)
Always select the lowest tier capable of solving the subtask with high quality:

| Tier | Default Model | Cost / Speed | When to Use Autonomously |
| :--- | :--- | :--- | :--- |
| **`fast`** | `gemini-3.8-flash-low` (`gemini-3.8-flash-lite`) | Lowest cost, 0 thinking overhead | Codebase scouting, file discovery, log/diff summarization, doc extraction, boilerplate & unit test drafting. |
| **`balanced`** | `gemini-3.8-flash-high` | Moderate cost, fast reasoning | Standard feature implementation, API routes, DB schemas (`prisma-db-architect`), automated QA (`qa-tester`), general code review. |
| **`heavy`** | `claude-sonnet-4-6` / `Gemini 4 Argon (High)` | Frontier reasoning (auto-fallback on quota limits) | Complex system architecture, security audits, subtle bug root-cause analysis, Clean Architecture backend (`ts-backend-coder`), UI/UX (`frontend-designer`). |

### 3. Parallel Context Multiplication (`invoke_sessions_parallel`)
Whenever a task can be decomposed into **2 or more independent tracks** (e.g., scouting two subsystems, auditing security + performance + tests, or implementing backend + frontend), call `invoke_sessions_parallel` to run N isolated context windows concurrently.

### 4. Recursive Sub-Sessions (Child Spawns Grandchild)
Every spawned session automatically receives `mesh_invoke_session`, `mesh_send_message`, `mesh_check_inbox`, and `mesh_wait_for_inbox` (up to `MAX_SESSION_DEPTH = 3`). A `heavy` architect session can autonomously spawn `fast` scout sub-sessions to gather file details without polluting the architect's context window.

💡 Example Prompts to Try in Your AI Client

Once connected, you can interact with the orchestrator naturally:

1. Cross-Session Specialist Delegation (Mesh Mode)

"Use invoke_session to spawn a 'SecurityAuditor' using model claude-sonnet-4-6 and task it with auditing src/server.ts. Run it in the background."

"Check our inbox with check_inbox to see what the SecurityAuditor reported."

"Send a follow-up to the auditor with send_session_message asking for remediation diffs."

"Broadcast an announcement to all active subagents using broadcast_session_message."

2. Autonomous Swarm Mode

"Use start_swarm to research best practices for caching and write a benchmark test in our workspace."

3. Structured Pipeline Mode

"Run the feature_implementation pipeline using run_pipeline with input topic: RateLimitingMiddleware."

4. Human-in-the-Loop Checkpoint

"Check job status using get_task_status. If there is a pending checkpoint, approve it using approve_checkpoint."

🖥️ Live Web Dashboard

Whenever the orchestrator runs, the embedded web dashboard is available at:

👉 http://localhost:4000

• Live Task Monitoring: Real-time progress percentage, active step descriptions, and status badges.
• Thought Transcripts: Live streaming of agent reasoning scratchpads and tool results via Server-Sent Events (SSE).
• Interactive Approvals: Visual banner with Approve and Reject buttons and feedback input for human checkpoints.
• Artifact Viewer: Preview generated Markdown and code outputs directly in the browser.

🛡️ Safety Modes & Sandboxing

The orchestrator enforces 3 security tiers configured in orchestrator.yaml or per-request:

All file operations are strictly scoped within security.allowed_workspaces.

🖥️ Platform Support

Runs on Windows, macOS, and Linux (Node.js ≥ 20).

• Override the agy location with binary_path in a provider or the AGY_BIN_PATH environment variable.
• allowed_workspaces accepts ~ and absolute paths. Windows drive roots such as D:/ are ignored on macOS/Linux, so one config file works everywhere.
• Local build on macOS/Linux:

  agy mcp add agent-orchestrator node "$PWD/dist/index.js" "$PWD/orchestrator.yaml"
  

📜 License

MIT License. Free to use, modify, and distribute.