mcp -hub

This MCP Server Hub acts as a central gateway to manage multiple MCP servers and hub-native tools from a single gateway client. It dynamically starts, stops, and reloads managed MCP servers and hub tools as you update its configuration. Your LLM clients (like Cline or Cursor) connect to the gateway client, which then proxies requests to the appropriate managed MCP server or hub tool. The hub exposes tools using namespaces based on serverId and toolName (serverId__toolName for managed servers, hub__toolName for hub tools), making it easy to discover and call capabilities across all connected MCP servers.

To use it, install dependencies, build, and run the gateway. You can configure multiple external MCP servers in mcpServers, add hub-native tools under hubTools, and optionally enable internal hub services. Changes to the dist/mcp_hub_config.json file are hot-reloaded, so you can update the list of managed servers or tools without restarting the gateway server.

Prerequisites:

• Node.js v20+ (recommended)
• npm
• Access to the external MCP servers you want to manage

Installation steps:

1. Clone the repository and navigate to the project root.
2. Install dependencies:

npm install

3. Build the gateway server and client code (copies mcp_hub_config.json to dist/):

npm run build

4. Start the gateway server:

npm start

5. Edit mcp_hub_config.json at the project root to configure mcpServers, hubTools, and settings. The running gateway watches dist/mcp_hub_config.json for live changes.

Notes:

• Ensure your external MCP servers are accessible and that you have the correct paths in their args.
• If you add or modify hub tools, keep the compiled module paths under dist/tools/ as expected by the hub.
• The gateway uses WebSocket on port 8081 by default; adjust in mcp_hub_config.json if needed.

Tips and common issues:

• Live reloading relies on dist/mcp_hub_config.json; after editing, save changes and verify the gateway logs show a config reload. If a managed server fails to restart, check the server command and paths in mcpServers.
• hubTools expect a compiled module at dist/tools/ with an exported handler (default if not specified) and an inputSchema export (Zod schema) for validation.
• The gateway supports dynamic management; ensure your environment has sufficient permissions to spawn/monitor external processes for mcpServers.
• For large tool sets, periodically review and prune hubTools to avoid unnecessary module loads.
• If using environment variables in mcpServers, document them in env per server for clarity.