MCP Orchestrator

The Magic Layer Between Your Agent and 1000+ MCP Servers

"Want to install Pandas MCP? It can analyze large CSV files efficiently..." Your agent suggests this at exactly the right moment. That's the magic.

🎯 The Problem

You're working with Claude/Cursor on a coding project:

• Agent gets stuck: "I can't analyze this 2GB CSV file efficiently"
• You don't know: There are 1000+ MCP servers out there, but which one solves this?
• Manual hassle: Even if you knew, you'd have to stop, install it, configure it, restart...
• Tool overload: If you connect all MCPs upfront, the agent gets confused (30-50% performance drop)

✨ The Vision (What We're Building)

You: "Claude, analyze sales_data.csv and show trends"

Agent: "💡 This CSV is large (2GB). I found a specialized tool:

**Pandas MCP** (score: 95)
- Best for CSV/Excel operations
- Handles millions of rows efficiently
- Built-in data cleaning

Install it? (takes ~30 sec)"

You: "Yes"

Agent: "✅ Pandas installed! Analyzing now..."
[continues working seamlessly with new capabilities]

Zero interruption. Pure magic.

🚀 How It Works

The MCP Orchestrator sits between your agent and the MCP ecosystem:

1. Intelligent Discovery: Agent realizes it needs help → Orch suggests relevant MCPs
2. Auto-Installation: User approves → Orch downloads and installs the MCP
3. Seamless Integration: New tools appear → Agent continues working
4. Just-in-Time Loading: Only connect MCPs when needed → Better performance

🏗️ Architecture

Agent (Claude/Cursor/etc.)
         ↓
   MCP Orchestrator (this server)
         ↓
   [Filesystem MCP] [GitHub MCP] [SQLite MCP] ...

📦 Installation

# Clone the repo
git clone <repo-url>
cd mcp-orchestrator

# Install dependencies
npm install

# Install at least one MCP server to test with
npm install -g @modelcontextprotocol/server-filesystem

🎮 Usage

Start the orchestrator

npm run dev

Test with MCP Inspector

npm run inspector

This will open a browser at http://localhost:6274 where you can:

1. See available meta-tools
2. Call list_available_mcps to browse the registry
3. Call connect_mcp to connect to an MCP
4. Use tools from connected MCPs

Available Meta-Tools

🎯 discover_mcps (THE MAGIC TOOL)

Intelligently discovers which MCPs would help with your current task.

Example:

{
  "taskDescription": "I need to analyze a large CSV file with sales data"
}

Returns:

{
  "recommendations": [
    {
      "id": "pandas",
      "name": "Pandas",
      "score": 95,
      "reasons": [
        "Best for CSV/Excel operations",
        "Handles millions of rows efficiently"
      ],
      "pros": ["Fast", "Mature ecosystem"],
      "cons": ["Heavy dependency"],
      "installTime": "~30 seconds"
    }
    // ... more recommendations
  ]
}

The agent uses this tool automatically when it senses it needs help.

connect_mcp

Connects to a specific MCP server (with auto-installation coming soon)

{
  "mcpId": "filesystem"
}

list_available_mcps

Browse all 10+ MCPs in the registry

list_active_mcps

Show currently connected MCPs

disconnect_mcp

Disconnect from an MCP

📋 Current Registry (MVP)

The orchestrator currently knows about these MCPs:

• filesystem - Read, write, and manage files and directories
• git - Git repository operations
• github - GitHub API integration
• sqlite - Query and manage SQLite databases
• postgres - Query and manage PostgreSQL databases
• fetch - Fetch web pages and make HTTP requests
• brave-search - Search the web using Brave Search API
• puppeteer - Browser automation
• slack - Slack API integration
• google-drive - Google Drive integration

Note: You need to install these MCPs separately for them to work.

🔮 Current Status & Roadmap

✅ What's Working Now (MVP)

• Intelligent Discovery: discover_mcps tool with context analysis
  • Extracts keywords, categories, task types
  • Ranks MCPs by relevance (scoring algorithm)
  • Returns top 5 recommendations with reasons
• Dynamic Connection: Connect/disconnect MCPs on-demand
• Tool Routing: Seamlessly proxy calls to connected MCPs
• Registry: 10 curated MCP servers (filesystem, git, github, sqlite, etc.)
• Node.js Support: Works with all Node.js MCPs via stdio

🚧 What's Next (The Magic)

Phase 1: Auto-Installation (CRITICAL) 🎯

This is what makes it feel magical

• [ ] Check if MCP is installed before connecting
• [ ] Auto-run npm install -g or pip install if missing
• [ ] Show installation progress to user
• [ ] Seamlessly continue after installation
• Goal: User says "yes" → 30 seconds later → tools are available

Phase 2: Proactive Suggestions

Make the agent smarter about when to suggest

• [ ] Enhanced tool descriptions (teach agent when to call discover)
• [ ] Add analyze_task_and_suggest meta-tool for proactive checking
• [ ] MCP notifications (tools/list_changed) after connecting
• [ ] Rich recommendations (pros, cons, install time, use cases)

Phase 3: Production Ready

• [ ] Sync with official MCP registry (1000+ servers)
• [ ] Support Python MCPs
• [ ] HTTP transport support
• [ ] Database layer (replace hardcoded registry)
• [ ] Performance metrics and analytics

Phase 4: Polish

• [ ] Auto-disconnect unused MCPs (LRU cache)
• [ ] Connection health checks
• [ ] Web dashboard for registry browsing
• [ ] Usage analytics

🧪 Testing

Run the proof-of-concept

npm run poc

This tests basic MCP spawning and connection.

Run the orchestrator

npm run dev

Test with an agent

Configure your MCP client (Claude Desktop, Cursor, etc.) to connect to the orchestrator via stdio.

Example config for Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "orchestrator": {
      "command": "node",
      "args": ["C:/path/to/mcp-orch/dist/index.js"]
    }
  }
}

💡 Key Design Decisions

How does the agent know when to suggest MCPs?

The agent is smart enough on its own. Modern agents (Claude, GPT-4) can:

• Recognize when they lack capabilities
• Read tool descriptions to understand when to call them
• Make decisions about when to extend themselves

We make it work by:

1. Clear tool descriptions - Tell the agent exactly when to call discover_mcps
2. Smart prompting - Agent learns from conversation patterns
3. Proactive tools - analyze_task_and_suggest tool for explicit checking

How does auto-installation work?

connect_mcp("pandas")
  → Check: is pandas-mcp installed?
  → No: Run `pip install mcp-server-pandas`
  → Spawn process and connect
  → Notify agent: "New tools available!"
  → Agent continues seamlessly

How does the agent continue working after installation?

MCP Protocol Notifications: After installing a new MCP, we send:

server.notification({
  method: 'notifications/tools/list_changed'
});

The agent receives this, refreshes its tool list, and sees the new tools. No interruption needed!

🎯 Tomorrow's Work

Priority 1: Build Auto-Installer

• src/auto-installer.ts - Check if installed, run npm/pip install
• Update connect_mcp tool to use auto-installer
• Test with filesystem MCP (should install if missing)

Priority 2: Rich Recommendations

• Add pros/cons/installTime to discovery results
• Update MCP registry with package names for installation
• Test discover → install → use workflow

Priority 3: Agent Integration Testing

• Test with Claude Desktop
• Verify proactive suggestions work
• Measure the "magic" feeling

🤝 Contributing

This is a work in progress. The goal: make MCP discovery feel like magic.

📄 License

MIT