Master Orchestrator

A central MCP server that connects to multiple MCP servers and intelligently routes user queries to the appropriate MCP tools, then aggregates and returns responses.

🚀 Quick Start (Interactive CLI)

The easiest way to get started is with our interactive CLI:

python src/cli.py

The CLI will guide you through:

• API key setup
• MCP server discovery
• MCP selection
• Interactive query interface

See CLI_QUICKSTART.md for detailed instructions.

Features

• 🔌 Multi-MCP Connection: Connect to multiple MCP servers simultaneously
• 🤖 AI-Powered Routing: Uses LLM to intelligently route queries (default)
• 🧠 Intelligent Routing: Analyzes queries to determine which MCP(s) to call
• 🔍 Tool Discovery: Automatically discovers available tools from connected MCPs
• 📊 Response Aggregation: Combines responses from multiple MCPs when needed
• ⚡ Async Execution: Parallel execution for faster responses
• 🎯 Query Analysis: Understands query intent to route to correct MCPs
• 🔄 Fallback Support: Automatically falls back to rule-based routing if AI fails

Architecture

User Query
    │
    ▼
┌─────────────────────┐
│  Master MCP Server  │
│  ┌───────────────┐  │
│  │ Query Analyzer│  │
│  └───────┬───────┘  │
│          │          │
│          ▼          │
│  ┌───────────────┐  │
│  │ MCP Router    │  │
│  └───────┬───────┘  │
│          │          │
└──────────┼──────────┘
           │
    ┌──────┴──────┐
    │             │
    ▼             ▼
┌─────────┐  ┌─────────┐
│ MCP #1  │  │ MCP #2  │
│ Router  │  │ Coding  │
└────┬────┘  └────┬────┘
     │            │
     └─────┬──────┘
           │
           ▼
    ┌──────────┐
    │ Response │
    │ Aggregator│
    └─────┬────┘
          │
          ▼
    User Response

Installation

cd master-mcp
pip install -r requirements.txt

AI Routing Setup (Optional)

The Master MCP works out-of-the-box without API keys using rule-based routing.

For enhanced AI-powered routing, set an API key:

# Option 1: OpenAI (default)
export OPENAI_API_KEY=your_key_here

# Option 2: Anthropic
export ANTHROPIC_API_KEY=your_key_here
export MASTER_MCP_AI_PROVIDER=anthropic
export MASTER_MCP_AI_MODEL=claude-3-5-haiku

Routing Modes:

Mode	API Key Required	Speed	Intelligence
Rule-based (default)	❌ No	⚡ Fast	Good
AI-powered	✅ Yes	🔄 +200ms	Excellent

To disable AI routing even if API key is set:

export MASTER_MCP_USE_AI=false

Configuration

Create a config.json file to register MCP servers:

{
  "mcp_servers": {
    "mcp-router": {
      "command": "python3",
      "args": ["/path/to/mcp-router/src/mcp_server.py"],
      "env": {}
    },
    "mcp-coding-agent": {
      "command": "python3",
      "args": ["/path/to/mcp-coding-agent/src/main.py"],
      "env": {}
    }
  }
}

Usage

As MCP Server (Cursor Integration) - Recommended

The Master MCP is now integrated with Cursor! See CURSOR_SETUP.md for detailed instructions.

Quick Start:

1. The Master MCP has been added to your ~/.cursor/mcp.json
2. Restart Cursor
3. Use it:

   @master-mcp query_mcp "What model should I use for debugging?"
   @master-mcp list_mcps
   

Benefits:

• 🎯 Auto-discovers all your existing MCPs
• 🤖 Intelligent query routing (AI or rule-based)
• 📊 Aggregates responses from multiple MCPs
• 🔌 Works out-of-the-box (no API key required for rule-based routing)

Standalone MCP Server

Add to any MCP client's configuration:

{
  "version": "1.0",
  "mcpServers": {
    "master-mcp": {
      "command": "python3",
      "args": ["/path/to/master-mcp/src/master_mcp_server.py"],
      "env": {
        "MASTER_MCP_USE_AI": "true"
      }
    }
  }
}

CLI Usage

python src/master_mcp_server.py --query "What model should I use for debugging?"

How It Works

1. Query Analysis: Analyzes user query to determine intent
2. MCP Selection: Selects appropriate MCP(s) based on query
3. Tool Selection: Chooses the right tool(s) from selected MCPs
4. Execution: Calls MCP tools (in parallel when possible)
5. Aggregation: Combines responses into a unified result
6. Response: Returns formatted response to user