🚀 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.

---

---

🎯 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

Clone or download the project

   cd d:\GENAI\AgentsCrossToolMCP

Create virtual environment

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

Install dependencies

   pip install -r requirements.txt

Configure environment variables

Create a .env file in the project root: ``env GROQ_API_KEY=your_groq_api_key_here ``

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:

Call run_research_graph(query, 5)
Display the multi-page research report
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

Open VS Code Settings (Ctrl+,)

Go to MCP Servers section

Add configuration:

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

Restart VS Code

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: ``python 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

Separation of Concerns

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

State Immutability Pattern

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

Error Handling

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

Extensibility

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

Adding New Agents

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

Adding New Tools

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

---

🐛 Troubleshooting

Issue: "GROQ_API_KEY not found"

Solution: Ensure .env file exists with valid API key ```powershell

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 ``powershell 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 ```python

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

Multi-Agent Research System MCP Server