multi-server mcp aggregation with unified endpoint
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.
Unique: Uses a bidirectional proxy architecture where the aggregator acts as both an MCP server (to clients) and MCP client (to backends), managing full process lifecycle and stdio communication for each backend rather than requiring pre-running servers or external orchestration
vs alternatives: Eliminates the need for clients to support multiple simultaneous connections by centralizing multiplexing server-side, unlike manual configuration of multiple client connections which hits hard limits in tools like Cursor
tool name conflict resolution with client compatibility
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.
Unique: Implements automatic bidirectional name mapping with server-based prefixing and character sanitization in a single pass during tool discovery, rather than requiring manual tool name configuration or client-side name resolution logic
vs alternatives: Avoids manual tool renaming or client configuration by automatically handling both naming conflicts and client compatibility constraints, whereas manual approaches require per-tool configuration and don't scale with new servers
ci/cd pipeline integration with automated testing and building
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.
Unique: Provides automated multi-platform binary building and release publishing via CI/CD pipeline, eliminating manual build and release steps for operators
vs alternatives: Enables automated testing and release workflows compared to manual building and publishing, and provides pre-built binaries for multiple platforms reducing deployment friction
per-server tool filtering and allowlisting
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.
Unique: Implements server-side allowlisting at the aggregator level rather than relying on backend server configuration, enabling centralized tool exposure control across multiple backends from a single configuration file
vs alternatives: Provides centralized tool filtering without modifying backend servers or requiring per-client configuration, whereas backend-level filtering would require changes to each server and client-side filtering would duplicate logic across clients
stdio-based process orchestration for backend mcp 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.
Unique: Implements careful stdout isolation and JSON-RPC message routing to prevent backend server logging from corrupting protocol streams, using a dedicated communication channel per backend server rather than multiplexing all servers over a single stdio connection
vs alternatives: Provides transparent process management without requiring pre-running servers or external orchestration tools, whereas alternatives like Docker Compose or systemd require separate configuration and don't provide unified tool aggregation
mcp protocol version control and client compatibility mode
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.
Unique: Provides environment-variable-based protocol version forcing and Cursor-specific compatibility mode rather than automatic protocol negotiation, allowing explicit control over protocol behavior for known client quirks
vs alternatives: Enables compatibility with specific MCP clients like Cursor without modifying client code, whereas automatic negotiation might not handle client-specific quirks or undocumented protocol expectations
json configuration-driven server and tool management
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.
Unique: Uses a single declarative JSON configuration file for all server topology and tool filtering rather than requiring separate configuration files per server or environment variables for each setting, enabling centralized management of complex multi-server setups
vs alternatives: Provides a single source of truth for MCP server configuration compared to environment-variable-based approaches which scatter configuration across multiple variables, or code-based configuration which requires recompilation
automatic tool discovery from backend mcp servers
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.
Unique: Performs automatic tool discovery at aggregator startup by querying backend MCP servers rather than requiring manual tool registration or maintaining a separate tool registry, enabling zero-configuration tool exposure
vs alternatives: Eliminates manual tool registration overhead compared to systems requiring explicit tool configuration, and provides accurate tool schemas directly from backends rather than relying on cached or manually-maintained metadata
+3 more capabilities