# 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:
```bash
cd /path/to/Multi-MCPServer
```
2. **Create and activate a virtual environment**:
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
3. **Install dependencies**:
```bash
pip install -r requirements.txt
```
## 🏃♂️ Running the Servers
### Start Individual MCP Servers
Run each server in separate terminals or background processes:
```bash
# 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
```bash
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
- **list_all_tools()**: Dynamically discovers and lists all available tools from all MCP servers
- **call_tool_on_server(server_id: int, tool_name: str, arguments: dict)**: Dynamically calls a specific tool on a specified server
### Example API Calls
#### Direct Server Calls
```bash
# 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
```bash
# 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}'
```
#### List All Tools
```bash
# List all available tools
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": "list_all_tools", "arguments": {}}, "id": 2}'
```
#### Call Tool Dynamically
```bash
# Call greet on server 1
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": "call_tool_on_server", "arguments": {"server_id": 1, "tool_name": "greet", "arguments": {"name": "World"}}}, "id": 3}'
```
Response:
```json
{
"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](https://modelcontextprotocol.io/)
- [FastMCP Documentation](https://github.com/modelcontextprotocol/python-sdk)
- [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification)</content>
<parameter name="filePath">/Users/arvindacharya/Desktop/Quadra-Projects/MCP/Multi-MCPServer/README.md
