MCP Server Hub / Gateway

Purpose: This project provides a central gateway to manage multiple MCP (Model Context Protocol) servers and expose hub-native tools, preventing the need to configure and run duplicate server processes for each LLM client (like Cline, Cursor, etc.). It supports dynamic configuration reloading, allowing managed servers and hub tools/services to be updated without restarting the main gateway server. Connect your LLM client to the single gateway-client endpoint provided by this project to access tools from all your managed MCP servers and the hub itself through one interface.

Architecture

The system consists of two main components within this repository:

1. Gateway Server (src/server.ts):
The core hub process that runs persistently.
Reads an initial configuration file (mcp_hub_config.json) during startup. Crucially, the build process copies this file to the dist/ directory, and the running server watches the dist/mcp_hub_config.json file for changes.
Dynamically manages the lifecycle (start, stop, monitor, restart) of underlying MCP servers defined in the mcpServers config section.
Dynamically loads/unloads/updates hub-native tools defined in the hubTools config section.
Supports configurable internal services (like exampleService) that react to config changes.
Listens for WebSocket connections from Gateway Clients (default port 8081).
Discovers tools from managed servers and exposes them with a serverId__toolName namespace.
Exposes hub-native tools with a hub__toolName namespace.
Routes tool calls received from Gateway Clients to the appropriate managed server or internal hub tool handler.

2. Gateway Client (src/client/client.ts):
Acts as the proxy server that LLM clients connect to via STDIO.
Connects to the running Gateway Server via WebSocket (with auto-reconnect).
Forwards MCP requests (like mcp_listTools, mcp_callTool) from the LLM Client to the Gateway Server.
Returns responses from the Gateway Server back to the LLM Client.
Periodically polls the Gateway Server for tool list updates to handle dynamic changes (configurable via CLIENT_TOOL_REFRESH_INTERVAL_MS env var, defaults to 5 minutes). (Does not work in Claude Desktop)
Restart the MCP client process to refresh the tool list.

flowchart LR
    subgraph "User Machine"
        LLM_Client1["LLM Client (e.g., Cline)"]
        LLM_Client2["LLM Client (e.g., Cursor)"]
subgraph "Gateway Client Process"

            style GatewayClientProcess fill:#f9f,stroke:#333,stroke-width:2px

            GatewayClient["Gateway Client App\n(client.ts)"]

        end
subgraph "Gateway Server Process"

            style GatewayServerProcess fill:#ccf,stroke:#333,stroke-width:2px

            GatewayServer["Gateway Server\n(server.ts)"]

            ConfigFile["dist/mcp_hub_config.json"] --- Watcher["File Watcher"]

            Watcher -- "Triggers Reload" --> GatewayServer

            MCPServer1["Managed MCP Server 1"]

            MCPServer2["Managed MCP Server 2"]

            HubTool["Hub Tool\n(e.g., exampleHubTool.ts)"]

            HubService["Hub Service\n(e.g., ExampleConfigurableService.ts)"]

        end

    end
LLM_Client1 -- "STDIO" --> GatewayClient

    LLM_Client2 -- "STDIO" --> GatewayClient

    GatewayClient -- "WebSocket" --> GatewayServer

    GatewayServer -- "Manages/Proxies" --> MCPServer1

    GatewayServer -- "Manages/Proxies" --> MCPServer2

    GatewayServer -- "Loads/Runs" --> HubTool

    GatewayServer -- "Uses" --> HubService

    GatewayServer -- "Reads/Watches" --> ConfigFile

Node.js (v20+ recommended)
npm
The underlying MCP servers you want to manage must be installed/accessible.

2. Installation & Build

```bash