README.md

---
title: Delegation MCP
emoji: 🚀
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
license: mit
short_description: Intelligent Multi-Agent Routing & Guidance
tags:
  - mcp-server
  - building-mcp-track-enterprise
  - multi-agent
  - agent-orchestration
---

# 🚀 Delegation MCP Server

**Intelligent Multi-Agent Routing & Guidance**

[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)]() [![License](https://img.shields.io/badge/license-MIT-blue)]() [![MCP](https://img.shields.io/badge/MCP-1.0-purple)]() [![Version](https://img.shields.io/badge/version-0.4.0-orange)]() [![Anthropic](https://img.shields.io/badge/Anthropic-Compliant-green)]()

> *Built for the MCP 1st Birthday Hackathon - Winter 2025*

## ⚡ Quick Start

```bash
# One command to install and configure everything
python install.py
```

**That's it!** Restart Claude Code and start delegating:

```
"scan this codebase for security vulnerabilities"
→ MCP suggests: "Delegate to Gemini"
→ Claude executes: gemini scan .

"design an authentication architecture"
→ MCP suggests: "Handle directly (Claude is best)"
→ Claude executes: (Internal reasoning)

"refactor the delegation engine"
→ MCP suggests: "Delegate to Aider"
→ Claude executes: aider --message "refactor delegation engine"
```

**Features**:
- ✅ **One-command installation** - 30 seconds to full setup
- ✅ **Intelligent Routing** - Rules + Capabilities analysis
- ✅ **Privacy-First** - Your code never passes through this server
- ✅ **Lightweight** - Minimal footprint, no heavy databases
- ✅ **Cross-platform** - Windows, Mac, Linux

---

## 🎮 Try the Interactive Demo

**[![Hugging Face Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces/Cduplar/multi-agent-mcp)**

Experience the routing intelligence in action! Our HF Space demo lets you:

### Interactive Features:
- 🧪 **Test Any Query** - See routing decisions in real-time
- 📊 **Routing Transparency** - View the complete decision-making process:
  - Task classification (security, architecture, refactoring, etc.)
  - Complexity assessment (simple/medium/complex)
  - Detected keywords and routing reasoning
  - CLI command that would be executed
- ⚙️ **Live Configuration** - Toggle agents and routing strategies to see how settings affect decisions
- 💡 **Example Queries** - Simple and complex multi-step scenarios

### Try This:
1. Visit the [HF Space](https://huggingface.co/spaces/Cduplar/multi-agent-mcp)
2. Enter: *"Audit the authentication system for SQL injection, XSS, and CSRF vulnerabilities"*
3. Watch it route to Gemini with full reasoning
4. Disable Gemini in settings → See it route to Claude instead!

**Want to test with real agents?** Duplicate the Space and add your API keys!

---

## 🌟 What Is This?

A **lightweight MCP server** that acts as a routing intelligence layer for AI coding agents. Instead of executing tasks itself (which creates a bottleneck and security risk), it analyzes your request and **guides** your main agent (like Claude Code) on which tool to use.

**Key Insight**: This follows the **Routing Guidance** pattern:
1. **Analyze**: The server analyzes the prompt (e.g., "audit security").
2. **Route**: It determines the best agent based on your **presets** and **rules**.
3. **Guide**: It returns the *exact command* to run.
4. **Execute**: The client (Claude) executes the command directly.

This ensures **zero lock-in**, **maximum privacy**, and **native performance**.

---

## 🎯 The Core Value Proposition

### Problem
Developers manually switch between AI agents, losing context and productivity:
- Claude for architecture
- Gemini for security analysis
- Aider for git operations
- Copilot for GitHub integration

### Solution
**One MCP server that tells your agent who to call:**

```
You → Claude Code → Delegation MCP → "Use Gemini for this" → Claude calls Gemini
```

**You work with ONE agent, but get the power of ALL agents.**

---

## 📦 Installation

### Prerequisites
- Python 3.10+
- At least one AI agent CLI installed:
  - [Gemini CLI](https://github.com/google/generative-ai-cli): `npm install -g @google/gemini-cli`
  - [Aider](https://aider.chat): `pip install aider-chat`
  - [Claude Code](https://claude.ai/download): `npm install -g @anthropic-ai/claude-code`
  - [GitHub Copilot](https://github.com/features/copilot): `npm install -g github/copilot`

### Automated Installation (Recommended)

```bash
# Clone repository
git clone https://github.com/carlosduplar/multi-agent-mcp.git
cd multi-agent-mcp

# One-command install
python install.py

# Or on Unix/Mac
bash install.sh
```

The installer will:
1. Check system requirements
2. Discover installed agents
3. Configure Claude Code automatically
4. Verify everything works

**Restart Claude Code and you're ready!**

---

## 🎯 How It Works

### Intelligent Routing Guidance

We use a hybrid approach to determine the best agent for the job:

1. **Rule-Based Presets**: Your configured rules take priority (e.g., "Always use Gemini for security").
2. **Capability Analysis**: If no rule matches, we analyze agent capabilities to find the best fit.

**Query**: "scan for vulnerabilities"

1. **Check Rules**: Matches `security_audit` preset? -> **Gemini**
2. **Guide**: Return guidance to use Gemini

### Example Interaction

**User**: "Audit my authentication code for SQL injection"

**Claude Code** calls `get_routing_guidance`:
```json
{
  "query": "Audit auth.py for SQL injection"
}
```

**MCP Server** responds:
```json
{
  "decision": "DELEGATE_TO: gemini",
  "agent": "gemini",
  "task_type": "security_audit",
  "cli_command": "gemini \"Audit auth.py for SQL injection\""
}
```

**Claude Code** then executes:
```bash
gemini "Audit auth.py for SQL injection"
```

---

## 🔧 MCP Tools

### `get_routing_guidance`
Get routing guidance for a task. Returns which agent should handle it and the exact CLI command to run.

```python
{
  "query": "Audit auth.py for SQL injection"
}
```

### `discover_agents`
Automatically discover available CLI agents on the system and register them.

```python
{
  "force_refresh": false  # Optional: force re-discovery
}
```

### `list_agents`
List all registered agents and their availability status.

### ⚡ Token Overhead

One of the key advantages of this MCP server is its **minimal context footprint**. Here's the actual token usage:

```
MCP Tools:
├─ get_routing_guidance: 601 tokens
├─ discover_agents:      584 tokens
└─ list_agents:          554 tokens
                         ─────────
Total MCP overhead:      1,739 tokens (0.9% of 200k context)
```

**What this means**:
- ✅ Less than 1% of your context budget
- ✅ Leaves 99%+ for actual code and conversation
- ✅ No heavy prompts or bloated instructions
- ✅ Intelligent routing without sacrificing context

Compare this to running multiple agent instances or complex orchestration frameworks that can consume 10-20% of your context just for coordination overhead.

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────┐
│  Claude Code (or other MCP client)      │
│  - User chats here                      │
│  - Calls get_routing_guidance           │
│  - EXECUTES the returned command        │
└──────────────┬──────────────────────────┘
               │ MCP Protocol (stdio)
               ▼
┌──────────────────────────────────────────┐
│  Delegation MCP Server                   │
│  - Analyzes task complexity & type       │
│  - Checks rules & capabilities           │
│  - Returns guidance (NO EXECUTION)       │
└──────────────────────────────────────────┘
```

### v0.4.0 - Lightweight Architecture

**Privacy & Security**:
- **No Code Execution**: The server never executes code or commands. It only suggests them.
- **No Data Persistence**: No databases or logs of your code are kept by the server.
- **Direct Connection**: Your agent talks directly to the delegated tool (e.g., Claude -> Gemini).

**Agent Auto-Discovery**:
- Automatically detects installed CLI agents (Claude, Gemini, Aider, etc.)
- Verifies agent availability
- Graceful error handling

---

## 🗂️ Project Structure

```
multi-agent-mcp/
├── src/delegation_mcp/
│   ├── server.py              # MCP server (Routing Guidance) ⭐
│   ├── delegation.py          # Routing logic & scoring
│   ├── orchestrator.py        # Agent registry
│   ├── agent_discovery.py     # System scanner for agents
│   ├── tool_discovery.py      # Tool definitions
│   ├── config.py              # Configuration handling
│   ├── cli.py                 # CLI tools
│   └── adapters/              # Agent definitions
│       ├── claude.py
│       ├── gemini.py
│       ├── copilot.py
│       └── aider.py
├── tools/                     # Tool definitions (JSON)
├── tests/                     # Comprehensive tests
└── config/                    # Default delegation rules
```

---

## 🚀 Roadmap

### ✅ Phase 1: Foundation (COMPLETE)
- MCP server with routing guidance
- Capability-based routing
- Agent auto-discovery
- Production-grade architecture

### 🔜 Phase 2: Intelligence (Q1 2026)
- ML-powered routing
- Learning from user feedback
- Custom agent definitions

### 🔮 Phase 3: Collaboration (Q2 2026)
- Complex multi-step workflows
- Parallel agent execution guidance

---

## 🤝 Contributing

We welcome contributions! Add new agent adapters, improve routing logic, or enhance documentation.

---

## 📄 License

MIT License - see [LICENSE](LICENSE)

---

## 🎯 The Vision

> **"You work with ONE agent, but get the power of ALL agents."**

Today's AI landscape has amazing specialists, but they work in silos. **Delegation MCP changes that.** It's the intelligence layer that lets agents collaborate, creating something greater than the sum of its parts.

---

**Built with ❤️ for the MCP ecosystem**