🚀 Multi-Agent Research System MCP Server

Advanced Multi-Agent Architecture for VS Code Copilot Integration

A next-generation Model Context Protocol (MCP) server that demonstrates how to build powerful multi-agent systems with sophisticated tooling, breaking away from traditional specialized-tool-only MCP implementations.

---

📋 Table of Contents

• Overview
• Architecture
• Key Features
• Technology Stack
• Project Structure
• Installation
• Configuration
• Usage
• Workflow Pipeline
• VS Code Integration
• API Reference
• Examples
• Development

---

🎯 Overview

This project represents a paradigm shift in MCP server design. While traditional MCP servers focus on exposing simple, specialized tools, this implementation leverages multi-agent orchestration to create a sophisticated research system that can be seamlessly integrated into VS Code Copilot.

The system combines three specialized AI agents with powerful internal tools to perform comprehensive research tasks—all exposed through simple, intuitive MCP tools.

Why This Matters

• Traditional MCP: Single-purpose tools exposed directly to clients
• This Approach: Multi-agent coordination, tool orchestration, and intelligent workflow management wrapped in a clean interface
• Result: More powerful, context-aware, and reliable results delivered through familiar tools

---

🏗️ Architecture

System Overview

┌─────────────────────────────────────────────────────────────┐
│                    VS Code Copilot                          │
└────────────────────────┬────────────────────────────────────┘
                         │
                    MCP Protocol (STDIO)
                         │
┌────────────────────────▼────────────────────────────────────┐
│              FastMCP Server (Entry Point)                   │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  Exposed Tools:                                        │ │
│  │  • run_research_graph(query, num_sources)             │ │
│  │  • workflow_info()                                     │ │
│  └────────────────────────────────────────────────────────┘ │
└─────┬──────────────────────────────────────────────────────┘
      │
      │ Invokes
      │
┌─────▼────────────────────────────────────────────────────────┐
│         LangGraph Workflow (State Management)                │
│                                                              │
│  START → Research Agent → Validator Agent → Final Output → END
│          Agent            Agent           Agent
└────┬─────────┬──────────────┬────────────────────────────────┘
     │         │              │
     ▼         ▼              ▼
  ┌──────────────────────────────────────────────────────────┐
  │       Internal Tools (Not Exposed to Client)            │
  │  ┌────────────────┐  ┌─────────────────────────────────┐│
  │  │  Web Tools     │  │  LLM Agents (Groq - 70B)        ││
  │  │  • web_search  │  │  • Research Analysis            ││
  │  │  • fetch_page  │  │  • Validation & Scoring         ││
  │  │  • search_news │  │  • Report Generation            ││
  │  └────────────────┘  └─────────────────────────────────┘│
  └──────────────────────────────────────────────────────────┘

Agent Pipeline

1. RESEARCH AGENT
   ├─ Performs web searches using DuckDuckGo
   ├─ Fetches detailed content from URLs
   ├─ Performs LLM-based analysis
   ├─ Extracts facts and insights
   └─ Outputs: summary, key_facts, insights

2. VALIDATOR AGENT
   ├─ Evaluates research quality
   ├─ Scores reliability (0-100)
   ├─ Identifies issues and gaps
   ├─ Provides improvement recommendations
   └─ Outputs: validation_score, reliability, status

3. FINAL OUTPUT AGENT
   ├─ Synthesizes all agent outputs
   ├─ Generates professional markdown report
   ├─ Organizes findings hierarchically
   ├─ Includes sources and recommendations
   └─ Outputs: final_report (professional documentation)

---

✨ Key Features

🤖 Multi-Agent Orchestration

• Three Specialized Agents: Research, Validation, and Output generation
• Sequential Workflow: Each agent refines the previous agent's output
• State Preservation: TypedDict-based state management ensures data consistency

🔧 Advanced Tooling

• Web Search: DuckDuckGo integration for source discovery
• Content Extraction: Beautiful Soup-based webpage parsing
• News Search: Specialized news discovery capability
• All Internal: Tools not exposed to clients—only results are shared

🧠 Intelligent Analysis

• LLM-Powered: Groq's Llama 3.3 (70B) for accurate analysis
• Temperature Control: Optimized settings per agent (Research: 0.3, Validation: 0.2, Output: 0.4)
• JSON Parsing: Structured output with fallback mechanisms

📊 Quality Assurance

• Validation Scoring: 0-100 confidence scoring system
• Reliability Assessment: Multi-factor reliability ratings
• Error Tracking: Issue identification and recommendations

🔐 Secure Integration

• Environment Variables: API keys managed via .env
• STDIO Transport: Safe MCP communication channel
• No Data Leakage: Internal tools hidden from client

---

🛠️ Technology Stack

Component	Technology	Purpose
Agent Framework	LangGraph	Workflow orchestration & state management
LLM Provider	Groq (Llama 3.3 70B)	Advanced reasoning & analysis
Language	Python 3.10+	Implementation language
MCP Framework	FastMCP	Server protocol & tool exposure
HTTP Client	HTTPX	Async web requests
HTML Parser	BeautifulSoup 4	Content extraction
Chat Models	LangChain	LLM integration abstraction

---

📂 Project Structure

AgentsCrossToolMCP/
├── server.py                      # FastMCP server & tool definitions
├── graph_workflow.py              # LangGraph workflow pipeline
├── state.py                       # Shared state TypedDict definition
├── requirements.txt               # Python dependencies
├── pyproject.toml                 # Project metadata
│
├── agents/                        # Multi-agent components
│   ├── __init__.py
│   ├── research_agent.py          # Source discovery & analysis
│   ├── validator_agent.py         # Quality validation & scoring
│   └── final_output_agent.py      # Report generation
│
└── tools/                         # Internal tool library
    ├── __init__.py
    ├── web_tools.py               # Web search, fetch, news search
    └── __pycache__/

---

📦 Installation

Prerequisites

• Python 3.10 or higher
• Groq API key (get one at https://console.groq.com)
• VS Code with Copilot extension

Setup Steps

1. Clone or download the project

   cd d:\GENAI\AgentsCrossToolMCP
   

2. Create virtual environment

   python -m venv .venv
   .\.venv\Scripts\Activate.ps1
   

3. Install dependencies

   pip install -r requirements.txt
   

4. Configure environment variables Create a .env file in the project root:

   GROQ_API_KEY=your_groq_api_key_here
   

5. Verify installation

   python server.py
   

   You should see the FastMCP banner and server startup messages.

---

⚙️ Configuration

Environment Variables

# Required
GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Optional (uses defaults if not set)
GROQ_MODEL=llama-3.3-70b-versatile    # Model for all agents
RESEARCH_TEMPERATURE=0.3               # Research agent creativity
VALIDATOR_TEMPERATURE=0.2              # Validator strictness
OUTPUT_TEMPERATURE=0.4                 # Output composition creativity

MCP Server Configuration

The MCP server is configured in VS Code through the settings:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "python",
      "args": ["d:\\GENAI\\AgentsCrossToolMCP\\server.py"],
      "disabled": false,
      "alwaysAllow": ["run_research_graph", "workflow_info"]
    }
  }
}

---

🚀 Usage

Via VS Code Copilot

Once connected, you can use the system directly in Copilot:

Example Prompt:

@my-mcp-server Use run_research_graph to research "AI safety in Large Language Models" 
with 5 sources and provide a comprehensive analysis.

Copilot will:

1. Call run_research_graph(query, 5)
2. Display the multi-page research report
3. Cite sources and validation metrics

Programmatic Usage

from server import run_research_graph
import asyncio

async def main():
    result = await run_research_graph(
        query="Is Indian GDP growing? Current growth rate and challenges",
        num_sources=5
    )
    print(result)

asyncio.run(main())

Command Line

# Start the server
python server.py

# In another terminal, test via MCP client
# (Configure in VS Code settings)

---

🔄 Workflow Pipeline

Step-by-Step Execution

1️⃣ Initialization

• User provides query and source count
• System initializes ResearchState object
• Workflow begins

2️⃣ Research Agent Processing

Input: query, num_sources
├─ web_search(query) → 5 search results
├─ fetch_webpage(url) for top 2 results → raw content
├─ LLM Analysis with tools
└─ Output: summary, key_facts, insights

3️⃣ Validation Agent Processing

Input: research_summary, key_facts
├─ LLM Assessment of quality
├─ Scoring (0-100)
├─ Reliability rating
└─ Output: validation_score, status, issues

4️⃣ Final Output Agent Processing

Input: all previous outputs + sources
├─ Combine all findings
├─ Format as markdown report
├─ Add structure & organization
└─ Output: final_report (professional document)

5️⃣ Return to Client

• MCP server returns final_report
• Copilot displays in editor
• Sources and validation metrics included

---

🔌 VS Code Integration

Setup Instructions

1. Open VS Code Settings (Ctrl+,)

2. Go to MCP Servers section

3. Add configuration:

   "mcpServers": {
     "my-mcp-server": {
       "command": "python",
       "args": ["d:\\GENAI\\AgentsCrossToolMCP\\server.py"],
       "disabled": false
     }
   }
   

4. Restart VS Code

5. Verify in Copilot Chat:

   • Open Copilot Chat (Ctrl+L)
   • Type @my-mcp-server
   • Should see available tools

Usage in Copilot

@my-mcp-server Can you research the latest developments in quantum computing
and provide a detailed analysis with key insights?

---

🔗 API Reference

Tool: run_research_graph

Purpose: Execute comprehensive research workflow

Parameters:

run_research_graph(
    query: str,              # Research topic/question
    num_sources: int = 5     # Number of sources to fetch
) -> str

Returns:

Professional markdown report containing:
- Executive Summary
- Key Findings
- Detailed Analysis
- Research Sources
- Validation Metrics
- Recommendations

Example:

report = await run_research_graph(
    query="Climate change impact on agricultural productivity",
    num_sources=5
)
print(report)

---

Tool: workflow_info

Purpose: Get information about the multi-agent system

Parameters: None

Returns:

String describing:
- Agent roles and responsibilities
- Available capabilities
- Tool information

Example:

info = await workflow_info()
print(info)

---

📚 Examples

Example 1: Economic Research

Query:

Query: India GDP growth rate 2024 2025 economic challenges obstacles
Sources: 5

Output includes:

• GDP growth statistics
• Economic challenges identified
• Market obstacles
• Expert recommendations
• Data reliability assessment

---

Example 2: Technology Trends

Query:

Query: Latest developments in quantum computing and AI integration
Sources: 8

Output includes:

• Recent breakthroughs
• Technical insights
• Industry trends
• Research opportunities
• Cross-domain applications

---

🧑‍💻 Development

Project Architecture Principles

1. Separation of Concerns

   • Agents focus on specific tasks
   • Tools handle data fetching
   • Server handles protocol translation

2. State Immutability Pattern

   • TypedDict ensures type safety
   • Operator.add for message accumulation
   • Clear state transitions

3. Error Handling

   • Graceful degradation for tool failures
   • LLM JSON parsing fallbacks
   • Comprehensive error messages

4. Extensibility

   • Easy to add new agents
   • Simple to integrate new tools
   • Flexible temperature/model parameters

Adding New Agents

1. Create new agent class in agents/
2. Implement async __call__(self, state) method
3. Add to graph in graph_workflow.py
4. Update state.py if needed

Adding New Tools

1. Create tool function in tools/web_tools.py
2. Decorate with @tool
3. Add to agent's bind_tools() call
4. Keep tools internal (not exposed via MCP)

---

🐛 Troubleshooting

Issue: "GROQ_API_KEY not found"

Solution: Ensure .env file exists with valid API key

# Verify .env exists
Test-Path .\.env

# Check content (don't share publicly)
Get-Content .\.env

Issue: MCP server won't start

Solution: Check dependencies and Python version

python --version  # Should be 3.10+
pip list | grep -i fastmcp

Issue: Web fetch fails (403 Forbidden)

Solution: Some websites block scraping. System handles this gracefully

• Validator agent scores lower
• System uses alternative sources
• Report still generated with available data

Issue: Slow response times

Solution: Configure fewer sources or optimize LLM

# Use fewer sources
run_research_graph(query, num_sources=3)

# Or increase timeout in web_tools.py
timeout=60.0  # Increase from 30.0

---

📊 Performance Metrics

Typical Execution Times

• Web Search: 2-3 seconds
• Content Fetch: 1-2 seconds per page
• Research Agent: 3-5 seconds
• Validation Agent: 2-3 seconds
• Final Output Agent: 2-3 seconds
• Total: ~10-15 seconds for 5 sources

Resource Requirements

• CPU: Minimal (network-bound)
• Memory: ~200-300 MB
• Network: Required (STDIO/HTTP requests)
• Storage: <50 MB code

---

🔐 Security & Privacy

• No Data Storage: Results not persisted
• API Key Protection: Via environment variables
• STDIO Transport: Encrypted by VS Code
• No Third-Party Analytics: Pure execution
• Tool Isolation: Internal tools never exposed

---

🌟 Why This Architecture?

Traditional MCP Limitations

User Request
    ↓
Tool Call
    ↓
Simple Result

Problems:

• No intelligence between tools
• User must coordinate multiple calls
• No quality validation
• Results not synthesized

This System's Advantages

User Request
    ↓
Workflow Graph
    ├─ Research Agent (intelligent search)
    ├─ Validator Agent (quality check)
    └─ Final Output Agent (synthesis)
    ↓
Professional Report

Benefits:

• Autonomous orchestration
• Intelligent analysis layers
• Built-in quality validation
• Professional output
• Single-call interface

---

VSCode Copilot Conversation

<img width="1375" height="745" alt="Screenshot 2025-11-12 170848" src="https://github.com/user-attachments/assets/5d36c8f1-ed2d-451d-a229-385a1a8041e0" /> <img width="1196" height="755" alt="Screenshot 2025-11-12 170936" src="https://github.com/user-attachments/assets/870df046-4dfd-4886-935b-8f6c9a699015" /> <img width="1217" height="649" alt="Screenshot 2025-11-12 170948 - Copy" src="https://github.com/user-attachments/assets/c63b37ff-ba0f-47b7-b747-6768a258eb4b" /> <img width="1238" height="638" alt="Screenshot 2025-11-12 171001" src="https://github.com/user-attachments/assets/eca92598-56cc-4c31-b253-ff130c0e4eba" />