MCP Hub

A centralized manager for Model Context Protocol (MCP) servers that provides:

Dynamic MCP server management and monitoring
REST API for tool execution and resource access
MCP Server marketplace (using Cline marketplace)
Real-time server status tracking
Client connection management
Process lifecycle handling

Overview

Hub Server vs MCP Servers

Hub Server (MCP Hub)
- Central management server that connects to and manages multiple MCP servers
- Provides unified API endpoints for clients to access MCP server capabilities
- Handles server lifecycle, health monitoring, and client connections
- Routes requests between clients and appropriate MCP servers
MCP Servers
- Individual servers that provide specific tools and resources
- Each server has its own capabilities (tools, resources, templates)
- Connected to and managed by the Hub server
- Process requests from clients through 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 (default: 3000)
  --config          Path to config file (required)
  --watch           Watch config file for changes (default: false)
  --shutdown-delay  Delay in milliseconds before shutting down when no clients are connected (default: 0)
  -h, --help       Show help information

The server outputs JSON-formatted status messages on startup and state changes:


{
  "status": "ready",
  "server_id": "mcp-hub",
  "version": "1.0.0",
  "port": 3000,
  "pid": 12345,
  "servers": [],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Nix

Nixpkgs install

comming...

Flake install

Just add it to your NixOS flake.nix or home-manager:


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

To integrate mcp-hub to your NixOS/Home Manager configuration, add the following to your environment.systemPackages or home.packages respectively:


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

Usage without install

If you want to use mcphub.nvim without having mcp-hub server in your PATH you can link the server under the hood adding the mcp-hub nix store path to the cmd command in the plugin config like

Nixvim example:


{ 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"
    })
  '';
}

# where
{
  # For nixpkgs (not available yet)
  mcp-hub = pkgs.mcp-hub;

  # For flakes
  mcp-hub = inputs.mcp-hub.packages."${system}".default;
}

Configuration

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


{
  "mcpServers": {
    "example-server": {
      "command": "npx",
      "args": ["example-server"],
      "env": {
        "API_KEY": "", // Will use process.env.API_KEY
        "DEBUG": "true", // Will use this value
        "SECRET_TOKEN": null // Will use process.env.SECRET_TOKEN
      },
      "disabled": false
    }
  }
}

Configuration Options

command: Command to start the MCP server
args: Array of command line arguments
env: Environment variables for the server. If a variable is specified with a falsy value (empty string, null, undefined), it will fall back to using the corresponding system environment variable if available.
disabled: Whether the server is disabled (default: false)

Example Integrations

Neovim Integration

The ravitemer/mcphub.nvim plugin provides seamless integration with Neovim, allowing direct interaction with MCP Hub from your editor:

Execute MCP tools directly from Neovim
Access MCP resources within your editing workflow
Real-time status updates in Neovim
Auto install mcp servers with marketplace addition

Logging

MCP Hub uses structured JSON logging for all events:


{
  "type": "error",
  "code": "TOOL_ERROR",
  "message": "Failed to execute tool",
  "data": {
    "server": "example-server",
    "tool": "example-tool",
    "error": "Invalid parameters"
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Log levels include:

info: Normal operational messages
warn: Warning conditions
debug: Detailed debug information
error: Error conditions (includes error code and details)

REST API

Health and Status

Health Check


GET /api/health

Response:


{
  "status": "ok",
  "server_id": "mcp-hub",
  "version": "1.0.0",
  "activeClients": 2,
  "timestamp": "2024-02-20T05:55:00.000Z",
  "servers": []
}

List MCP Servers


GET /api/servers

Get Server Info


GET /api/servers/:name/info

Refresh Server Capabilities


POST /api/servers/:name/refresh

Response:


{
  "status": "ok",
  "server": {
    "name": "example-server",
    "capabilities": {
      "tools": ["tool1", "tool2"],
      "resources": ["resource1", "resource2"],
      "resourceTemplates": []
    }
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Refresh All Servers


POST /api/refresh

Response:


{
  "status": "ok",
  "servers": [
    {
      "name": "example-server",
      "capabilities": {
        "tools": ["tool1", "tool2"],
        "resources": ["resource1", "resource2"],
        "resourceTemplates": []
      }
    }
  ],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Start Server


POST /api/servers/:name/start

Response:


{
  "status": "ok",
  "server": {
    "name": "example-server",
    "status": "connected",
    "uptime": 123
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Stop Server


POST /api/servers/:name/stop?disable=true|false

The optional disable query parameter can be set to true to disable the server in the configuration.

Response:


{
  "status": "ok",
  "server": {
    "name": "example-server",
    "status": "disconnected",
    "uptime": 0
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Client Management

Register Client


POST /api/client/register
{
  "clientId": "unique_client_id"
}

Unregister Client


POST /api/client/unregister
{
  "clientId": "unique_client_id"
}

Marketplace Integration

List Available Servers


GET /api/marketplace

Query Parameters:

search: Filter by name, description, or tags
category: Filter by category
tags: Filter by comma-separated tags
sort: Sort by "newest", "stars", or "name"

Response:


{
  "items": [
    {
      "mcpId": "github.com/user/repo/server",
      "name": "Example Server",
      "description": "Description here",
      "category": "search",
      "tags": ["search", "ai"],
      "githubStars": 100,
      "isRecommended": true,
      "createdAt": "2024-02-20T05:55:00.000Z"
    }
  ],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Get Server Details


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

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

Response:


{
  "server": {
    "mcpId": "github.com/user/repo/server",
    "name": "Example Server",
    "description": "Description here",
    "githubUrl": "https://github.com/user/repo",
    "readmeContent": "# Server Documentation...",
    "llmsInstallationContent": "Installation guide..."
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

MCP Server Operations

Execute Tool


POST /api/servers/:name/tools
{
  "tool": "tool_name",
  "arguments": {}
}

Access Resource


POST /api/servers/:name/resources
{
  "uri": "resource://uri"
}

Real-time Updates

The Hub Server provides real-time updates via Server-Sent Events (SSE) at /api/events. Connect to this endpoint to receive real-time updates about server status, client connections, and capability changes.

Event Types

server_info - Initial connection information


{
  "server_id": "mcp-hub",
  "version": "1.0.0",
  "status": "connected",
  "pid": 12345,
  "port": 3000,
  "activeClients": 1,
  "timestamp": "2024-02-20T05:55:00.000Z"
}

server_ready - Server started and ready


{
  "status": "ready",
  "server_id": "mcp-hub",
  "version": "1.0.0",
  "port": 3000,
  "pid": 12345,
  "servers": [],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

client_registered/unregistered - Client connection events


{
  "activeClients": 2,
  "clientId": "client_123",
  "timestamp": "2024-02-20T05:55:00.000Z"
}

tool_list_changed - Server's tools list has changed


{
  "type": "TOOL",
  "server": "example-server",
  "tools": ["tool1", "tool2"],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

resource_list_changed - Server's resources list has changed


{
  "type": "RESOURCE",
  "server": "example-server",
  "resources": ["resource1", "resource2"],
  "resourceTemplates": [],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Error Handling

MCP Hub implements a comprehensive error handling system with custom error classes for different types of errors:

Error Classes

ConfigError: Configuration-related errors (invalid config, missing fields)
ConnectionError: Server connection issues (failed connections, transport errors)
ServerError: Server startup/initialization problems
ToolError: Tool execution failures
ResourceError: Resource access issues
ValidationError: Request validation errors

Each error includes:

Error code for easy identification
Detailed error message
Additional context in the details object
Stack trace for debugging

Example error structure:


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

Error Categories

Configuration Errors
- Invalid config format
- Missing required fields
- Environment variable issues
Server Management Errors
- Connection failures
- Lost connections
- Capability fetch issues
- Server startup problems
Request Processing Errors
- Invalid parameters
- Server availability
- Tool execution failures
- Resource access issues
Client Management Errors
- Registration failures
- Duplicate registrations
- Invalid client IDs

Architecture

Hub Server Lifecycle


sequenceDiagram
    participant H as Hub Server
    participant M1 as MCP Server 1
    participant M2 as MCP Server 2
    participant C as Client

    Note over H: Server Start
    activate H
    H->>+M1: Connect
    M1-->>-H: Connected + Capabilities
    H->>+M2: Connect
    M2-->>-H: Connected + Capabilities

    Note over C,H: Client Interactions
    C->>H: Register Client
    H-->>C: Servers List & Capabilities
    
    C->>H: Call Tool (M1)
    H->>M1: Execute Tool
    M1-->>H: Tool Result
    H-->>C: Response

    C->>H: Access Resource (M2)
    H->>M2: Get Resource
    M2-->>H: Resource Data
    H-->>C: Response

    Note over H: Server Management
    H->>H: Monitor Server Health
    H->>H: Track Server Status
    H->>H: Update Capabilities

    Note over H: Shutdown Process
    C->>H: Unregister
    H->>M1: Disconnect
    H->>M2: Disconnect
    deactivate H

The Hub Server coordinates communication between clients and MCP servers:

Starts and connects to configured MCP servers
Manages client registrations
Routes tool execution and resource requests
Handles server monitoring and health checks
Performs clean shutdown of all connections

MCP Server Management


flowchart TB
    A[Hub Server Start] --> B{Config Available?}
    B -->|Yes| C[Load Server Configs]
    B -->|No| D[Use Default Settings]
    
    C --> E[Initialize Connections]
    D --> E
    
    E --> F{For Each MCP Server}
    F -->|Enabled| G[Attempt Connection]
    F -->|Disabled| H[Skip Server]
    
    G --> I{Connection Status}
    I -->|Success| J[Fetch Capabilities]
    I -->|Failure| K[Log Error]
    
    J --> L[Store Server Info]
    K --> M[Mark Server Unavailable]
    
    L --> N[Monitor Health]
    M --> N
    
    N --> O{Health Check}
    O -->|Healthy| P[Update Capabilities]
    O -->|Unhealthy| Q[Attempt Reconnect]
    
    Q -->|Success| P
    Q -->|Failure| R[Update Status]
    
    P --> N
    R --> N

The Hub Server actively manages MCP servers through:

Configuration-based server initialization
Connection and capability discovery
Health monitoring and status tracking
Automatic reconnection attempts
Server state management

Request Handling


sequenceDiagram
    participant C as Client
    participant H as Hub Server
    participant M as MCP Server
    
    Note over C,H: Tool Execution Flow
    C->>H: POST /api/servers/{name}/tools
    H->>H: Validate Request
    H->>H: Check Server Status
    
    alt Server Not Connected
        H-->>C: Error: Server Unavailable
    else Server Connected
        H->>M: Execute Tool
        
        alt Tool Success
            M-->>H: Tool Result
            H-->>C: Success Response
        else Tool Error
            M-->>H: Error Details
            H-->>C: Error Response
        end
    end
    
    Note over C,H: Resource Access Flow
    C->>H: POST /api/servers/{name}/resources
    H->>H: Validate URI
    H->>H: Check Server Status
    
    alt Valid Resource
        H->>M: Request Resource
        M-->>H: Resource Data
        H-->>C: Resource Content
    else Invalid Resource
        H-->>C: 404 Not Found
    end

All client requests follow a standardized flow:

Request validation
Server status verification
Request routing to appropriate MCP server
Response handling and error management

Requirements

Node.js >= 18.0.0

Todo

[ ] Implement custom marketplace rather than depending on mcp-marketplace

Acknowledgements

Cline mcp-marketplace - For providing the MCP server marketplace endpoints that power MCP Hub's marketplace integration

Описание

Тип

MCP Hub

Overview

Hub Server vs MCP Servers

Installation

Basic Usage

CLI Options

Nix

Nixpkgs install

Flake install

Usage without install

Configuration

Configuration Options

Example Integrations

Neovim Integration

Logging

REST API

Health and Status

Health Check

List MCP Servers

Get Server Info

Refresh Server Capabilities

Refresh All Servers

Start Server

Stop Server

Client Management

Register Client

Unregister Client

Marketplace Integration

List Available Servers

Get Server Details

MCP Server Operations

Execute Tool

Access Resource

Real-time Updates

Event Types

Error Handling

Error Classes

Error Categories

Architecture

Hub Server Lifecycle

MCP Server Management

Request Handling

Requirements

Todo

Acknowledgements