MCP Hub

MCP Hub acts as a central coordinator between clients and multiple MCP servers, making it easy to utilize capabilities from multiple servers through a single interface.

Key Features

Dynamic Server Management:
- Start, stop, enable/disable servers on demand
- Real-time configuration updates with automatic server reconnection
- Support for 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

The main management server that:

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

Individual servers that:

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": "", // Will use process.env.API_KEY
          "DEBUG": "true", // Will use this value
          "SECRET_TOKEN": null // Will use process.env.SECRET_TOKEN
        },
        "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 based on the configuration fields provided.

STDIO Server Options

command: Command to start the local 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)

SSE Server Options

url: The URL of the remote SSE server endpoint
headers: Optional HTTP headers for the SSE connection (e.g., for authentication)
disabled: Whether the server is disabled (default: false)

Server Type Detection

The server type (STDIO or SSE) is automatically determined based on the presence of specific fields:

If command is present → STDIO server
If url is present → SSE server

Note: A server configuration cannot mix STDIO and SSE fields - it must be one type or the other.

Nix

Nixpkgs install

coming...

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;
}

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

REST API

Health and Status

Health Check

GET /api/health

The health endpoint provides comprehensive status information including:

Current hub state (starting, ready, restarting, restarted, stopping, stopped, error)
Connected server statuses and capabilities
Active SSE connection details
Detailed connection metrics
Error state details if applicable

Response:

{
  "status": "ok",
  "state": "ready",
  "server_id": "mcp-hub",
  "activeClients": 2,
  "timestamp": "2024-02-20T05:55:00.000Z",
  "servers": [],
  "connections": {
    "totalConnections": 2,
    "connections": [
      {
        "id": "client-uuid",
        "state": "connected",
        "connectedAt": "2024-02-20T05:50:00.000Z",
        "lastEventAt": "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"
}

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/start
Content-Type: application/json

{
  "server_name": "example-server"
}

Response:

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

Stop Server

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

{
  "server_name": "example-server"
}

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"
}

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/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": {}
}

Response:

{
  "result": {
    "messages": [
      {
        "role": "assistant",
        "content": {
          "type": "text",
          "text": "Text response example"
        }
      },
      {
        "role": "assistant",
        "content": {
          "type": "image",
          "data": "base64_encoded_image_data",
          "mimeType": "image/png"
        }
      }
    ]
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Restart Hub

POST /api/restart

Reloads the configuration file and restarts all MCP servers.

Response:

{
  "status": "ok",
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Real-time Events System

MCP Hub implements a comprehensive real-time events system using Server-Sent Events (SSE) at /api/events. This endpoint provides live updates about server status, configuration changes, capability updates, and more.

Hub States

The hub server transitions through several states during its lifecycle:

State	Description
`starting`	Initial startup, loading configuration
`ready`	Server is running and ready to handle requests
`restarting`	Reloading configuration/reconnecting servers
`restarted`	Configuration reload complete
`stopping`	Graceful shutdown in progress
`stopped`	Server has fully stopped
`error`	Error state (includes error details)

You can monitor these states through the /health endpoint or SSE events.

Event Types

MCP Hub emits several types of events:

Core Events

heartbeat - Periodic connection health check

{
  "connections": 2,
  "timestamp": "2024-02-20T05:55:00.000Z"
}

hub_state - Hub server state changes

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

log - Server log messages

{
  "type": "info",
  "message": "Server started",
  "data": {},
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Subscription Events

config_changed - Configuration file changes detected

{
  "type": "config_changed",
  "newConfig": {},
  "isSignificant": true,
  "timestamp": "2024-02-20T05:55:00.000Z"
}

servers_updating - Server updates in progress

{
  "type": "servers_updating",
  "changes": {
    "added": ["server1"],
    "removed": [],
    "modified": ["server2"],
    "unchanged": ["server3"]
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

servers_updated - Server updates completed

{
  "type": "servers_updated",
  "changes": {
    "added": ["server1"],
    "removed": [],
    "modified": ["server2"],
    "unchanged": ["server3"]
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

tool_list_changed - Server's tools list updated

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

resource_list_changed - Server's resources/templates updated

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

prompt_list_changed - Server's prompts list updated

{
  "type": "prompt_list_changed",
  "server": "example-server",
  "prompts": ["prompt1", "prompt2"],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Connection Management

Each SSE connection is assigned a unique ID
Connections are automatically cleaned up on client disconnect
Connection statistics available via /health endpoint
Optional auto-shutdown when no clients are connected

Logging

MCP Hub uses structured JSON logging for all events. Logs are written to both console and file at ~/.mcp-hub/logs/mcp-hub.log:

{
  "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 (includes configuration changes)
error: Error conditions (includes error code and stack trace)

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

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"
}

Architecture

Hub Server Lifecycle

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

    Note over H: Server Start (state: starting)
    activate H
    
    Note over H: Config Loading
    H->>H: Load & Validate Config
    H->>H: Watch Config File
    H->>H: Initialize SSE Manager
    
    Note over H: Server Connections (state: ready)
    H->>+M1: Connect
    M1-->>-H: Connected + Capabilities
    H->>+M2: Connect
    M2-->>-H: Connected + Capabilities
    H-->>C: hub_state (ready)

    Note over C,H: Client Setup
    C->>H: Connect to /api/events (SSE)
    H-->>C: connection_opened
    
    Note over C,H: Client Operations
    C->>H: Execute Tool (HTTP)
    H->>M1: Execute Tool
    M1-->>H: Tool Result
    H-->>C: HTTP Response
    
    Note over H,C: Real-time Updates
    H->>H: Detect Config Change
    H-->>C: servers_updating (SSE)
    H->>M1: Reconnect with New Config
    M1-->>H: Updated Capabilities
    H-->>C: servers_updated (SSE)

    Note over H,C: Server Events
    M2->>H: Tool List Changed
    H-->>C: tool_list_changed (SSE)
    
    Note over H: Shutdown Process
    Note over C,H: Client Disconnects
    H-->>C: hub_state (stopping) (SSE)
    H->>M1: Disconnect
    H->>M2: Disconnect
    H-->>C: hub_state (stopped) (SSE)
    deactivate H

The Hub Server coordinates communication between clients and MCP servers:

Starts and connects to configured MCP servers
Handles SSE client connections and events
Routes tool and resource requests to appropriate servers
Monitors server health and maintains capabilities
Manages graceful startup/shutdown processes

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
    C->>H: POST /api/servers/tools (HTTP)
    H->>H: Validate Request & Server
    
    alt Server Not Connected
        H-->>C: 503 Server Unavailable (HTTP)
    else Server Connected
        H->>M: Execute Tool
        
        alt Success
            M-->>H: Tool Result
            H-->>C: Result Response (HTTP)
        else Error
            M-->>H: Error Details
            H-->>C: Error Response (HTTP)
            H-->>C: log (SSE Event)
        end
    end
    
    Note over C,H: Resource Access
    C->>H: POST /api/servers/resources (HTTP)
    H->>H: Validate URI & Template
    
    alt Invalid Resource
        H-->>C: 404 Not Found (HTTP)
    else Server Not Connected
        H-->>C: 503 Unavailable (HTTP)
    else Valid Request
        H->>M: Request Resource
        
        alt Success
            M-->>H: Resource Data
            H-->>C: Resource Content (HTTP)
        else Error
            M-->>H: Error Details
            H-->>C: Error Response (HTTP)
            H-->>C: log (SSE Event)
        end
    end
    
    Note over C,H: Prompt Execution
    C->>H: POST /api/servers/prompts (HTTP)
    H->>H: Validate Prompt & Args
    
    alt Invalid Prompt
        H-->>C: 404 Not Found (HTTP)
    else Server Not Connected
        H-->>C: 503 Unavailable (HTTP)
    else Valid Request
        H->>M: Execute Prompt
        
        alt Success
            M-->>H: Messages Array
            H-->>C: Messages Response (HTTP)
        else Error
            M-->>H: Error Details
            H-->>C: Error Response (HTTP)
            H-->>C: log (SSE Event)
        end
    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

Name		Name	Last commit message	Last commit date
Latest commit History 96 Commits
.github		.github
.vscode		.vscode
examples		examples
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.md		LICENSE.md
README.md		README.md
SECURITY.md		SECURITY.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
flake.lock		flake.lock
flake.nix		flake.nix
mcp-servers.json		mcp-servers.json
nodemon.json		nodemon.json
package-lock.json		package-lock.json
package.json		package.json
vitest.config.js		vitest.config.js

License

ravitemer/mcp-hub

Folders and files

Latest commit

History

Repository files navigation

MCP Hub

Key Features

Components

Hub Server

MCP Servers

Installation

Basic Usage

CLI Options

Configuration

Configuration Options

STDIO Server Options

SSE Server Options

Server Type Detection

Nix

Nixpkgs install

Flake install

Usage without install

Example Integrations

Neovim Integration

REST API

Health and Status

Health Check

List MCP Servers

Get Server Info

Refresh Server Capabilities

Refresh All Servers

Start Server

Stop Server

Marketplace Integration

List Available Servers

Get Server Details

MCP Server Operations

Execute Tool

Access Resource

Get Prompt

Restart Hub

Real-time Events System

Hub States

Event Types

Core Events

Subscription Events

Connection Management

Logging

Error Handling

Error Classes

Architecture

Hub Server Lifecycle

MCP Server Management

Request Handling

Requirements

Todo

Acknowledgements

About

Topics

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks

Releases 22

Sponsor this project

Packages 0

Contributors 3

Languages

Packages