Multi-MCP Server

A distributed Model Context Protocol (MCP) server setup featuring multiple independent MCP servers and a master aggregator server. This project demonstrates how to build and orchestrate MCP-based services for tool calling and result aggregation.

🚀 Features

• Multiple MCP Servers: Three specialized MCP servers running on separate ports

  • Server 1: Greeting service

  • Server 2: Mathematical operations

  • Server 3: Text manipulation

• Master Aggregator: A central MCP server that orchestrates calls to all three servers

• HTTP Transport: Stateless HTTP-based communication using JSON-RPC 2.0

• Async Support: Fully asynchronous implementation for high performance

• Easy Deployment: Simple setup with virtual environment and uvicorn

📋 Prerequisites

• Python 3.8+

• Virtual environment (recommended)

🛠️ Installation

1. Clone the repository (if applicable) or navigate to the project directory:

   cd /path/to/Multi-MCPServer

2. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

🏃‍♂️ Running the Servers

Start Individual MCP Servers

Run each server in separate terminals or background processes:

# Server 1 (Port 8001)
PORT=8001 uvicorn mcp_server1:app --host 0.0.0.0 --port 8001

# Server 2 (Port 8002)
PORT=8002 uvicorn mcp_server2:app --host 0.0.0.0 --port 8002

# Server 3 (Port 8003)
PORT=8003 uvicorn mcp_server3:app --host 0.0.0.0 --port 8003

Start Master Aggregator Server

uvicorn master_mcp:app --host 0.0.0.0 --port 8000

📖 Usage

Available Tools

Server 1 Tools

• greet(name: str): Returns a personalized greeting message

Server 2 Tools

• add(a: float, b: float): Returns the sum of two numbers

Server 3 Tools

• reverse_text(text: str): Returns the reversed text

Master Server Tools

• aggregate_results(input_text: str): Calls all three servers and aggregates their results

Example API Calls

Direct Server Calls

# Greet
curl -X POST http://localhost:8001/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "greet", "arguments": {"name": "World"}}, "id": 1}'

# Add numbers
curl -X POST http://localhost:8002/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "add", "arguments": {"a": 10, "b": 20}}, "id": 1}'

# Reverse text
curl -X POST http://localhost:8003/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "reverse_text", "arguments": {"text": "hello"}}, "id": 1}'

Aggregated Results

# Aggregate all results
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "aggregate_results", "arguments": {"input_text": "test"}}, "id": 1}'

Response:

{
  "greet_result": "Hello, test! — from MCP Server 1",
  "add_result": "30.0",
  "reverse_text_result": "tset"
}

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐
│   Master MCP    │────│   Server 1      │
│   (Port 8000)   │    │   (Port 8001)   │
└─────────────────┘    └─────────────────┘
         │                       │
         └───────────────────────┼───────────────────────┐
                                 │                       │
                    ┌─────────────────┐    ┌─────────────────┐
                    │   Server 2      │    │   Server 3      │
                    │   (Port 8002)   │    │   (Port 8003)   │
                    └─────────────────┘    └─────────────────┘

• Master Server: Orchestrates calls to individual servers

• Individual Servers: Specialized MCP servers with unique tools

• HTTP Transport: All communication uses HTTP with JSON-RPC 2.0 over Server-Sent Events

🔧 Configuration

• Ports: Configurable via PORT environment variable (defaults: 8001, 8002, 8003)

• Host: Default 0.0.0.0 for external access

• Transport Security: Configurable via TransportSecuritySettings

🧪 Testing

Run the servers and use the provided curl examples to test functionality.

📦 Dependencies

• fastmcp: MCP server framework

• httpx: Async HTTP client

• uvicorn: ASGI server

• fastapi: Web framework

See requirements.txt for full list.

🤝 Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Troubleshooting

Common Issues

1. Port already in use: Change the PORT environment variable

2. Connection refused: Ensure all servers are running

3. JSON parsing errors: Check request format matches JSON-RPC 2.0 specification

Logs

Check server logs for detailed error information. Enable debug logging by setting LOG_LEVEL=DEBUG.

📚 Additional Resources

• Model Context Protocol Specification

• FastMCP Documentation

• JSON-RPC 2.0 Specification /Users/arvindacharya/Desktop/Quadra-Projects/MCP/Multi-MCPServer/README.md