MCP Aggregator Server

Unified MCP interface that proxies requests to multiple backend MCP servers.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     MCP Client                              │
│              (Claude, IDE, etc.)                            │
└────────────────────┬────────────────────────────────────────┘
                     │
                     │ Connect to single endpoint
                     ▼
┌─────────────────────────────────────────────────────────────┐
│         Aggregator MCP Server (Port 8003)                   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Unified MCP Interface                               │   │
│  │  - 19 tools total (2 health + 10 memory + 7 vector) │   │
│  │  - Handles routing internally                        │   │
│  │  - Single /mcp/sse & /mcp/messages endpoint          │   │
│  └──────────────────────────────────────────────────────┘   │
└────────┬──────────────────────────────────────────────────┬──┘
         │                                                  │
         │ HTTP Proxy                                       │ HTTP Proxy
         ▼                                                  ▼
┌──────────────────────┐                        ┌──────────────────────┐
│  ZepAI Memory Server │                        │  LTM Vector Server   │
│  (Port 8002)         │                        │  (Port 8000)         │
│                      │                        │                      │
│ - Knowledge Graph    │                        │ - Vector Database    │
│ - Conversation Memory│                        │ - Code Indexing      │
│ - 10 tools           │                        │ - 7 tools            │
└──────────────────────┘                        └──────────────────────┘

Features

• Unified Interface: Single MCP endpoint for all connected servers
• Transparent Proxying: Automatically routes requests to appropriate backend servers
• Health Monitoring: Built-in health checks for all connected servers
• Retry Logic: Automatic retry with exponential backoff for failed requests
• Error Handling: Comprehensive error handling and logging
• Extensible: Easy to add new backend servers

Installation

1. Install dependencies:

pip install -r requirements.txt

2. Configure environment (edit .env):

# Aggregator Server
AGGREGATOR_HOST=0.0.0.0
AGGREGATOR_PORT=8003

# Memory Server (FastMCP Server)
MEMORY_SERVER_URL=http://localhost:8002
MEMORY_SERVER_TIMEOUT=30

# Graph Server (for future use)
GRAPH_SERVER_URL=http://localhost:8000
GRAPH_SERVER_TIMEOUT=30

Running

Start all servers in order:

Terminal 1 - LTM Vector Server (Port 8000):

cd LTM
python mcp_server/server_streamable_http.py

Terminal 2 - ZepAI FastMCP Server (Port 8002):

cd ZepAI/fastmcp_server
python server_http.py

Note: This automatically loads the Memory Layer and exposes both FastAPI + MCP on port 8002

Terminal 3 - MCP Aggregator (Port 8003):

cd mcp-aggregator
python aggregator_server.py

See START_SERVERS.md for detailed startup guide.

Available Tools

Health & Status

• health_check() - Check health of all connected servers
• get_server_info() - Get information about connected servers

Memory Server Tools (Port 8002)

Search

• memory_search(query, project_id, limit, use_llm_classification) - Search knowledge graph
• memory_search_code(query, project_id, limit) - Search code memories

Ingest

• memory_ingest_text(text, project_id, metadata) - Ingest plain text
• memory_ingest_code(code, language, project_id, metadata) - Ingest code
• memory_ingest_json(data, project_id, metadata) - Ingest JSON data
• memory_ingest_conversation(conversation, project_id) - Ingest conversation

Admin

• memory_get_stats(project_id) - Get project statistics
• memory_get_cache_stats() - Get cache statistics

LTM Vector Server Tools (Port 8000)

Repository Processing

• ltm_process_repo(repo_path) - Process repository for vector indexing

Vector Search

• ltm_query_vector(query, top_k) - Query vector database for semantic code search
• ltm_search_file(filepath) - Search for specific file in vector database

File Management

• ltm_add_file(filepath) - Add file to vector database
• ltm_delete_by_filepath(filepath) - Delete file from vector database
• ltm_delete_by_uuids(uuids) - Delete vectors by UUIDs

Code Analysis

• ltm_chunk_file(file_path) - Chunk file using AST-based chunking

Testing

1. Check Server Health

curl http://localhost:8003/mcp/sse

2. Access OpenAPI Docs

http://localhost:8003/docs

3. Test a Tool via MCP

# Using MCP client
mcp-client http://localhost:8003/mcp health_check

Configuration

Environment Variables

Variable	Default	Description
AGGREGATOR_HOST	0.0.0.0	Aggregator server host
AGGREGATOR_PORT	8003	Aggregator server port
MEMORY_SERVER_URL	http://localhost:8002	Memory server URL
MEMORY_SERVER_TIMEOUT	30	Memory server timeout (seconds)
GRAPH_SERVER_URL	http://localhost:8000	Graph server URL
GRAPH_SERVER_TIMEOUT	30	Graph server timeout (seconds)
LOG_LEVEL	INFO	Logging level
MAX_RETRIES	3	Max retries for failed requests
RETRY_DELAY	1	Delay between retries (seconds)
HEALTH_CHECK_INTERVAL	30	Health check interval (seconds)

Adding New Backend Servers

To add a new backend server (e.g., Graph Server):

1. Update config.py:

GRAPH_SERVER_URL = os.getenv("GRAPH_SERVER_URL", "http://localhost:8000")
GRAPH_SERVER_TIMEOUT = int(os.getenv("GRAPH_SERVER_TIMEOUT", "30"))

2. Update mcp_client.py:

class AggregatorClients:
    def __init__(self):
        # ... existing clients ...
        self.graph_client = MCPServerClient(
            "Graph Server",
            config.GRAPH_SERVER_URL,
            config.GRAPH_SERVER_TIMEOUT
        )

3. Add tools in aggregator_server.py:

@mcp.tool()
async def graph_query(cypher: str) -> Dict[str, Any]:
    """Query Neo4j graph database"""
    clients = await get_clients()
    return await clients.graph_client.proxy_request(
        "POST",
        "/query",
        json_data={"cypher": cypher},
        retries=config.MAX_RETRIES
    )

Troubleshooting

Connection Refused

• Ensure all backend servers are running
• Check URLs in .env file
• Verify ports are not blocked by firewall

Timeout Errors

• Increase MEMORY_SERVER_TIMEOUT or GRAPH_SERVER_TIMEOUT in .env
• Check backend server performance
• Verify network connectivity

Health Check Failing

• Run health_check() tool to diagnose
• Check backend server logs
• Verify backend servers are responding

Development

Project Structure

mcp_aggregator/
├── aggregator_server.py    # Main MCP server
├── config.py               # Configuration management
├── mcp_client.py           # HTTP clients for backend servers
├── requirements.txt        # Python dependencies
├── .env                    # Environment variables
├── __init__.py             # Package initialization
└── README.md               # This file

Adding Logging

import logging
logger = logging.getLogger(__name__)
logger.info("Message")
logger.error("Error")

Future Enhancements

• [ ] Add Graph/Vector DB server integration
• [ ] Implement caching layer
• [ ] Add request rate limiting
• [ ] Implement server load balancing
• [ ] Add metrics/monitoring
• [ ] Support for server discovery
• [ ] WebSocket support for real-time updates

License

Same as parent project (Innocody)