MCP HubMCP Hub
ravitemer

mcp-hub

by: ravitemer

A centralized manager for Model Context Protocol (MCP) servers with dynamic server management and monitoring

62created 20/02/2025
Visit
management
monitoring

📌Overview

Purpose: MCP Hub is designed to centralize and manage Model Context Protocol (MCP) servers, enabling dynamic server management and seamless client interactions.

Overview: MCP Hub serves as a management layer for multiple MCP servers, providing a unified API for clients to access various server capabilities. It facilitates server lifecycle management, health monitoring, and client connection handling, enhancing the efficiency and organization of complex server architectures.

Key Features:

  • Dynamic MCP Server Management: MCP Hub connects and manages multiple servers, overseeing their lifecycles and health, ensuring seamless operation without interruption.

  • REST API for Resource Access: A standardized API enables clients to execute tools and access resources across different MCP servers, streamlining interactions and improving integration workflows.

  • Real-time Server Status Tracking: The hub provides live updates on server health and client activities, facilitating quick responsiveness to changes and enhancing overall system reliability.

MCP Hub

npm version
License: MIT

MCP Hub acts as a central coordinator between clients and multiple MCP servers, enabling the use of multiple servers' capabilities through a single interface.

Key Features

  • Dynamic Server Management

    • Start, stop, enable/disable servers on demand
    • Real-time configuration updates with automatic server reconnection
    • Supports both local (stdio) and remote (SSE) MCP servers
    • Health monitoring and automatic recovery

  • Unified REST API

    • Execute tools from any connected server
    • Access resources and resource templates
    • Real-time status updates via Server-Sent Events (SSE)
    • Full CRUD operations for server management

  • Real-time Events & Monitoring

    • Live server status and capability updates
    • Client connection tracking
    • Tool and resource list change notifications
    • Structured JSON logging with file output

  • Client Connection Management

    • Simple SSE-based client connections via /api/events
    • Automatic connection cleanup on disconnect
    • Optional auto-shutdown when no clients connected
    • Real-time connection state monitoring

  • Process Lifecycle Management

    • Graceful startup and shutdown handling
    • Proper cleanup of server connections
    • Error recovery and reconnection

Components

Hub Server

  • Maintains connections to multiple MCP servers
  • Provides unified API access to server capabilities
  • Handles server lifecycle and health monitoring
  • Manages SSE client connections and events
  • Processes configuration updates and server reconnection

MCP Servers

  • Provide specific tools and resources
  • Can be local processes (STDIO) or remote endpoints (SSE)
  • Have their own set of capabilities (tools, resources, templates)
  • Are dynamically managed by the hub

Installation

npm install -g mcp-hub

Basic Usage

Start the hub server:

mcp-hub --port 3000 --config path/to/config.json

CLI Options

Options:
  --port            Port to run the server on (required)
  --config          Path to config file (required)
  --watch           Watch config file for changes, only updates affected servers (default: false)
  --auto-shutdown   Whether to automatically shutdown when no clients are connected (default: false)
  --shutdown-delay  Delay in milliseconds before shutting down when auto-shutdown is enabled (default: 0)
  -h, --help        Show help information

Configuration

MCP Hub uses a JSON configuration file to define managed servers:

{
  "mcpServers": {
    "stdio-server": {
      "command": "npx",
      "args": ["example-server"],
      "env": {
        "API_KEY": "", 
        "DEBUG": "true", 
        "SECRET_TOKEN": null 
      },
      "disabled": false
    },
    "sse-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer token",
        "Content-Type": "application/json"
      },
      "disabled": false
    }
  }
}

Configuration Options

MCP Hub supports two types of servers: STDIO (local) and SSE (remote). The server type is automatically determined from the configuration fields.

STDIO Server Options

  • command: Command to start the local MCP server
  • args: Array of command line arguments
  • env: Environment variables for the server; falsy values fall back to system env variables
  • disabled: Whether the server is disabled (default: false)

SSE Server Options

  • url: The URL of the remote SSE server endpoint
  • headers: Optional HTTP headers for SSE connection (e.g., authentication)
  • disabled: Whether the server is disabled (default: false)
Server Type Detection
  • If command is present → STDIO server
  • If url is present → SSE server

Servers cannot mix STDIO and SSE fields.

Nix

Nixpkgs install

coming...

Flake install

Add to your NixOS flake.nix or home-manager:

inputs = {
  mcp-hub.url = "github:ravitemer/mcp-hub";
  ...
}

Add to your environment.systemPackages or home.packages:

inputs.mcp-hub.packages."${system}".default

Usage without install

You can configure mcphub.nvim with the mcp-hub nix store path:

{ mcphub-nvim, mcp-hub, ... }:
{
  extraPlugins = [mcphub-nvim];
  extraConfigLua = ''
    require("mcphub").setup({
        port = 3000,
        config = vim.fn.expand("~/mcp-hub/mcp-servers.json"),
        cmd = "${mcp-hub}/bin/mcp-hub"
    })
  '';
}

Setting mcp-hub in nixpkgs or flakes accordingly.

Example Integrations

Neovim Integration

The ravitemer/mcphub.nvim plugin provides integration with Neovim to:

  • Execute MCP tools directly
  • Access MCP resources within editing workflow
  • Real-time status updates
  • Auto install MCP servers with marketplace integration

REST API

Health and Status

Health Check

GET /api/health

Returns overall hub state, connected server statuses, active SSE connections, connection metrics, and error states.

Example response excerpt:

{
  "status": "ok",
  "state": "ready",
  "activeClients": 2,
  "servers": [],
  "connections": { "totalConnections": 2 },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

List MCP Servers

GET /api/servers

Get Server Info

POST /api/servers/info
Content-Type: application/json

{
  "server_name": "example-server"
}

Refresh Server Capabilities

POST /api/servers/refresh
Content-Type: application/json

{
  "server_name": "example-server"
}

Refresh All Servers

POST /api/refresh

Start Server

POST /api/servers/start
Content-Type: application/json

{
  "server_name": "example-server"
}

Stop Server

POST /api/servers/stop?disable=true|false
Content-Type: application/json

{
  "server_name": "example-server"
}

Marketplace Integration

List Available Servers

GET /api/marketplace

Supports filtering by search, category, tags, and sorting.

Get Server Details

POST /api/marketplace/details
Content-Type: application/json

{
  "mcpId": "github.com/user/repo/server"
}

MCP Server Operations

Execute Tool

POST /api/servers/tools
Content-Type: application/json

{
  "server_name": "example-server",
  "tool": "tool_name",
  "arguments": {}
}

Access Resource

POST /api/servers/resources
Content-Type: application/json

{
  "server_name": "example-server",
  "uri": "resource://uri"
}

Get Prompt

POST /api/servers/prompts
Content-Type: application/json

{
  "server_name": "example-server",
  "prompt": "prompt_name",
  "arguments": {}
}

Example prompt response contains messages array with assistant content.

Restart Hub

POST /api/restart

Reloads the configuration file and restarts MCP servers.

Real-time Events System

MCP Hub uses Server-Sent Events (SSE) at /api/events for live updates on:

  • Server status and capability changes
  • Configuration changes
  • Tool, resource, and prompt list updates

Hub States

The hub server lifecycle states include:

  • starting: Initial startup
  • ready: Running and ready
  • restarting: Reloading config/reconnecting
  • restarted: Reload complete
  • stopping: Graceful shutdown in progress
  • stopped: Fully stopped
  • error: Error state

Event Types

Core Events

  • heartbeat: Connection health checks
  • hub_state: State changes of hub server
  • log: Server log messages

Subscription Events

  • config_changed: Configuration file changes
  • servers_updating: Server updates in progress
  • servers_updated: Server updates completed
  • tool_list_changed: Tools list updated for a server
  • resource_list_changed: Resources/templates updated
  • prompt_list_changed: Prompts updated

Connection Management

  • Each SSE connection has a unique ID
  • Automatic cleanup on disconnect
  • Statistics available via /health
  • Optional auto-shutdown when no clients connected

Logging

MCP Hub uses structured JSON logging, output to console and to files at ~/.mcp-hub/logs/mcp-hub.log.

Log levels:

  • info: Operational messages
  • warn: Warnings
  • debug: Debug information including config changes
  • error: Errors with codes and stack traces

Logs are rotated daily and kept for 30 days by default.

Error Handling

Custom error classes include:

  • ConfigError: Configuration errors
  • ConnectionError: Server connection issues
  • ServerError: Server startup problems
  • ToolError: Tool execution failures
  • ResourceError: Resource access issues
  • ValidationError: Request validation errors

Error responses include code, message, context, and timestamp.

Example:

{
  "code": "CONNECTION_ERROR",
  "message": "Failed to communicate with server",
  "details": {
    "server": "example-server",
    "error": "connection timeout"
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Architecture

Hub Server Lifecycle

The hub server starts by loading configuration, establishes connections to MCP servers, manages SSE clients, routes requests between clients and servers, monitors health, and handles graceful shutdown.

MCP Server Management

  • Load and validate config
  • Initialize connections to MCP servers
  • Fetch and store capabilities
  • Monitor server health and reconnect if needed

Request Handling

Client requests (tool execution, resource access, prompts) undergo validation, server availability checks, routing to MCP servers, and error handling with appropriate HTTP responses.

Requirements

  • Node.js >= 18.0.0

Todo

  • Implement custom marketplace instead of relying on mcp-marketplace

Acknowledgements

  • Cline mcp-marketplace — MCP server marketplace endpoints powering MCP Hub's marketplace integration