MCP Aggregator

Implements a proxy pattern that bridges MCP clients to multiple backend MCP servers through a single stdio endpoint. The aggregator launches and manages child processes for each configured backend server, establishes JSON-RPC communication channels with each, and presents all discovered tools through a unified interface. This solves the fundamental limitation of MCP clients like Cursor that can only connect to 2-3 servers simultaneously by multiplexing connections server-side.

Implements a three-layer name management system to handle tool naming conflicts across multiple backend servers while maintaining compatibility with MCP clients like Cursor. Tools are automatically prefixed with server identifiers (e.g., 'shortcut_search_stories'), sanitized by replacing dashes with underscores for Cursor compatibility, and mapped bidirectionally so sanitized names route back to original names for backend invocation. This prevents tool name collisions while preserving backend tool semantics.

Includes CI/CD pipeline configuration for automated testing, building, and releasing the MCP aggregator. The pipeline runs tests on code changes, builds binaries for multiple platforms (Linux/Darwin, amd64/arm64), and publishes releases to GitHub. This enables developers to contribute with confidence that changes are tested, and operators to deploy pre-built binaries without building from source. The pipeline is configured via GitHub Actions or similar CI/CD systems.

Provides configurable allowlists for each backend MCP server to selectively expose only specified tools through the aggregator. Tool filtering is defined in the JSON configuration via 'tools.allowed' arrays per server, enabling fine-grained control over which tools are discoverable and invokable by clients. This allows operators to restrict tool exposure based on security policies, licensing, or organizational requirements without modifying backend servers.

Manages the full lifecycle of backend MCP server processes by launching them as child processes, establishing stdio communication channels, and handling JSON-RPC message routing over those channels. The system carefully isolates stdout to prevent backend server logging from corrupting the JSON-RPC protocol stream, implements error handling for process failures, and maintains bidirectional communication with each backend server. This enables the aggregator to transparently invoke tools on remote servers as if they were local.

Supports forcing specific MCP protocol versions via the 'MCP_PROTOCOL_VERSION' environment variable and includes Cursor-specific adjustments configurable via 'MCP_CURSOR_MODE'. This allows the aggregator to adapt its protocol behavior to match client expectations, ensuring compatibility with different MCP client implementations that may have varying protocol support or quirks. The system can present different protocol versions to clients while maintaining compatibility with backend servers.

Uses a declarative JSON configuration file to specify all backend MCP servers, their launch commands, tool allowlists, and aggregator behavior. The configuration system parses server definitions, tool filtering rules, and environment variables from a single config file, enabling operators to manage the entire aggregator topology without code changes. Configuration is loaded at startup and applied to all subsequent tool discovery and invocation operations.

Automatically discovers available tools from each connected backend MCP server by querying their tool schemas at startup. The discovery process retrieves tool names, descriptions, input schemas, and other metadata from each backend, aggregates them with server-based prefixes and name sanitization, and presents the unified tool set to clients. This eliminates the need for manual tool registration or configuration while maintaining accurate tool metadata for client-side tool selection and parameter validation.

Routes tool invocation requests from clients to the correct backend MCP server based on tool name prefixes and the bidirectional name mapping. When a client invokes a tool with a sanitized name (e.g., 'shortcut_search_stories'), the aggregator maps it back to the original tool name, identifies the source backend server from the prefix, and forwards the invocation to that backend. The aggregator then returns the tool result to the client, transparently handling the routing and name translation.

Provides a logging system for tracking aggregator operations, backend server communications, tool discovery, and tool invocations. Logs capture JSON-RPC message exchanges, process lifecycle events, configuration loading, and error conditions, enabling operators to debug issues and monitor aggregator behavior. The logging system is configurable and can be directed to files or stdout for integration with log aggregation systems.

Provides Docker support for containerized deployment of the MCP aggregator, including Dockerfile for building container images and Docker Compose examples for orchestrating aggregator instances with backend MCP servers. The containerization approach enables easy deployment across different environments while maintaining consistent configuration and dependencies. Container images can be built from source or pulled from registries, and environment variables can be passed to configure aggregator behavior.