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 │ │ │ │ - 4 agent tools (search/query only) │ │ │ │ - 6 Innocody triggers (HTTP endpoints) │ │ │ │ - 3 admin endpoints (HTTP only) │ │ │ └──────────────────────────────────────────────────────┘ │ └────────┬──────────────────────────────────────────────────┬──┘ │ │ │ HTTP Proxy │ HTTP Proxy ▼ ▼ ┌──────────────────────┐ ┌──────────────────────┐ │ ZepAI Memory Server │ │ LTM Server │ │ (Port 8002) │ │ (Port 8000) │ │ │ │ │ │ - Knowledge Graph │ │ - Vector Database │ │ - Conversation Memory│ │ - Code Indexing │ │ - 4 tools │ │ - Knowledge Graph │ │ │ │ - 8 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

Install dependencies:

pip install -r requirements.txt

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

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):

Update :

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

Update :

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

Add tools in :

@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)

MCP Aggregator Server

MCP Aggregator Server

Architecture

Features

Installation

Running

Start all servers in order:

Available Tools

Health & Status

Memory Server Tools (Port 8002)

Search

Ingest

Admin

LTM Vector Server Tools (Port 8000)

Repository Processing

Vector Search

File Management

Code Analysis

Testing

1. Check Server Health

2. Access OpenAPI Docs

3. Test a Tool via MCP

Configuration

Environment Variables

Adding New Backend Servers

Troubleshooting

Connection Refused

Timeout Errors

Health Check Failing

Development

Project Structure

Adding Logging

Future Enhancements

License

Related Resources

Appeared in Searches

New MCP Servers

MCP directory API