The mcp-server-multiverse is a middleware solution designed to run multiple, isolated instances of MCP servers simultaneously. It addresses the challenge of managing conflicting configurations and namespaces when using multiple instances of the same server type. Each "universe" created by this server maintains its own configuration, filesystem access, and function naming, allowing developers to run multiple MySQL, Git, or filesystem servers without conflicts.

Key features include automatic server restart on file changes during development, and a JSON-based configuration system for defining server instances with custom commands, arguments, and environment variables. This enables seamless integration with AI models by providing access to diverse, isolated resources. The core value lies in simplifying complex development workflows and enhancing flexibility when working with multiple AI-driven projects or contexts. It integrates by configuring the claude_desktop_config.json file to launch multiple mcp-server-multiverse instances.

Isolated Server Instances

The core function of mcp-server-multiverse is to enable the simultaneous execution of multiple, isolated instances of the same MCP server type. Each instance operates within its own "universe," complete with separate configurations, filesystem access, and function naming conventions. This isolation prevents conflicts and allows developers to manage multiple contexts or projects using identical server types. For example, a developer can run two mcp-server-mysql instances, each connected to a different database (e.g., one for development and one for production), without any interference. This is achieved by namespacing the functions exposed by each server instance using a configurable prefix. The server uses JSON configuration files to define each universe, specifying the command to execute, arguments, environment variables, and path resolution rules.

Automatic Server Restart

During development, the mcp-server-multiverse can automatically restart a registered MCP server upon detecting file changes. This feature streamlines the development and testing process by eliminating the need for manual server restarts after each code modification. When enabled via the fileWatch configuration, the server monitors a specified directory for changes. Upon detecting a change, it performs a graceful restart of the associated MCP server. This ensures that the latest code changes are immediately reflected in the running server instance. For instance, a developer working on a custom MCP server can configure fileWatch to monitor the build directory. Every time the code is recompiled, the mcp-server-multiverse will automatically restart the server, allowing for rapid iteration and testing.

JSON-Based Configuration

The mcp-server-multiverse utilizes a flexible JSON-based configuration system to define and manage multiple server instances. This configuration system allows developers to specify various parameters for each server instance, including the command to execute, arguments, environment variables, and path resolution rules. The JSON configuration provides a clear and structured way to define the multiverse setup, making it easy to manage and maintain. For example, a developer can define a multiverse.json file that specifies two instances of mcp-server-filesystem, each pointing to a different root directory. The pathResolution feature can also be used to hide the root path from the client, providing an additional layer of security and abstraction.

Function Hiding

The hideFunctions feature allows developers to selectively hide specific functions exposed by the wrapped MCP servers. This provides a mechanism to restrict access to potentially dangerous or unnecessary functions, enhancing security and simplifying the server interface. By specifying a list of function names in the hideFunctions array within the server configuration, those functions will not be registered with the main MCP server and will be unavailable to the client. For example, when using mcp-server-github, a developer might choose to hide functions like create_repository and delete_repository to prevent accidental or malicious repository modifications. This feature is particularly useful for creating different permission levels for different server instances or for limiting the capabilities exposed to AI models.

Server Enabling/Disabling

The enabled flag provides a simple way to selectively enable or disable specific servers within the mcp-server-multiverse configuration without completely removing their configuration. Setting the enabled flag to false for a particular server instance will prevent it from being started, while retaining its configuration for future use. This is particularly useful during development and testing, allowing developers to easily toggle servers on and off as needed. For example, a developer might temporarily disable a mcp-server-github instance while testing a new feature that does not require GitHub access, or disable a server that is causing conflicts with other services. This feature simplifies the management of complex multiverse configurations and allows for flexible experimentation.