MCP Hub
MCP Hub acts as a central coordinator for MCP servers and clients, providing two key interfaces:
- Management Interface (/api/*): Manage multiple MCP servers through a unified REST API and web UI
- MCP Server Interface (/mcp): Connect ANY MCP client to access ALL server capabilities through a single endpoint
This dual-interface approach means you can manage servers through the Hub's UI while MCP clients (Claude Desktop, Cline, etc.) only need to connect to one endpoint (localhost:37373/mcp) to access all capabilities. Implements MCP 2025-03-26 specification.
Feature Support
Simplified Client Configuration
Configure all MCP clients with just one endpoint:
{
"mcpServers" : {
"Hub": {
"url" : "http://localhost:37373/mcp"
}
}
}
The Hub automatically:
- Namespaces capabilities to prevent conflicts (e.g.,
filesystem__searchvsdatabase__search) - Routes requests to the appropriate server
- Updates capabilities in real-time when servers are added/removed
- Handles authentication and connection management
Key Features
-
Unified MCP Server Endpoint (/mcp):
- Single endpoint for ALL MCP clients to connect to
- Access capabilities from all managed servers through one connection
- Automatic namespacing prevents conflicts between servers
- Real-time capability updates when servers change
- Simplified client configuration - just one endpoint instead of many
-
Dynamic Server Management:
- Start, stop, enable/disable servers on demand
- Real-time configuration updates with automatic server reconnection
- Support for local (STDIO) and remote (streamable-http/SSE) MCP servers
- Health monitoring and automatic recovery
- OAuth authentication with PKCE flow
- Header-based token authentication
-
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
-
Workspace Management:
- Track active MCP Hub instances across different working directories
- Global workspace cache in XDG-compliant state directory
- Real-time workspace updates via SSE events
- API endpoints to list and monitor active workspaces
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
Connected services that:
- Provide tools, resources, templates, and prompts
- Support two connectivity modes:
- Script-based STDIO servers for local operations
- Remote servers (streamable-http/SSE) with OAuth support
- Implement real-time capability updates
- Support automatic status recovery
- Maintain consistent interface across transport types
Installation
npm install -g mcp-hub
Basic Usage
Start the hub server:
mcp-hub --port 3000 --config path/to/config.json
# Or with multiple config files (merged in order)
mcp-hub --port 3000 --config ~/.config/mcphub/global.json --config ./.mcphub/project.json
CLI Options
Options:
--port Port to run the server on (required)
--config Path to config file(s). Can be specified multiple times. Merged in order. (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 JSON configuration files to define managed servers with universal ${} placeholder syntax for environment variables and command execution.
VS Code Configuration Compatibility
MCP Hub provides seamless compatibility with VS Code's .vscode/mcp.json configuration format, enabling you to use the same configuration files across both VS Code and MCP Hub.
Supported Features
Server Configuration Keys
Both mcpServers and servers keys are supported:
{
"servers": {
"github": {
"url": "https://api.githubcopilot.com/mcp/"
},
"perplexity": {
"command": "npx",
"args": ["-y", "server-perplexity-ask"],
"env": {
"API_KEY": "${env:PERPLEXITY_API_KEY}"
}
}
}
}
Variable Substitution
MCP Hub supports VS Code-style variable substitution:
- Environment Variables:
${env:VARIABLE_NAME}or${VARIABLE_NAME} - Workspace Variables:
${workspaceFolder},${userHome},${pathSeparator} - Command Execution:
${cmd: command args}
Supported Predefined Variables:
${workspaceFolder}- Directory where mcp-hub is running${userHome}- User's home directory${pathSeparator}- OS path separator (/ or )${workspaceFolderBasename}- Just the folder name${cwd}- Alias for workspaceFolder${/}- VS Code shorthand for pathSeparator
VS Code Input Variables
For ${input:} variables used in VS Code configs, use the MCP_HUB_ENV environment variable:
# Set input variables globally
export MCP_HUB_ENV='{"input:api-key":"your-secret-key","input:database-url":"postgresql://..."}'
# Then use in config
{
"servers": {
"myserver": {
"env": {
"API_KEY": "${input:api-key}"
}
}
}
}
Migration from VS Code
Existing .vscode/mcp.json files work directly with MCP Hub. Simply point MCP Hub to your VS Code configuration:
mcp-hub --config .vscode/mcp.json --port 3000
Multiple Configuration Files
MCP Hub supports loading multiple configuration files that are merged in order. This enables flexible configuration management:
- Global Configuration: System-wide settings (e.g.,
~/.config/mcphub/global.json) - Project Configuration: Project-specific settings (e.g.,
./.mcphub/project.json) - Environment Configuration: Environment-specific overrides
When multiple config files are specified, they are merged with later files overriding earlier ones:
# Global config is loaded first, then project config overrides
mcp-hub --port 3000 --config ~/.config/mcphub/global.json --config ./.mcphub/project.json
Merge Behavior:
mcpServerssections are merged (server definitions from later files override earlier ones)- Other top-level properties are completely replaced by later files
- Missing config files are silently skipped
Universal Placeholder Syntax
${ENV_VAR}or${env:ENV_VAR}- Resolves environment variables${cmd: command args}- Executes commands and uses output${workspaceFolder}- Directory where mcp-hub is running${userHome}- User's home directory${pathSeparator}- OS path separator${input:variable-id}- Resolves from MCP_HUB_ENV (VS Code compatibility)nullor""- Falls back toprocess.env
Configuration Examples
Local STDIO Server
{
"mcpServers": {
"local-server": {
"command": "${MCP_BINARY_PATH}/server",
"args": [
"--token", "${API_TOKEN}",
"--database", "${DB_URL}",
"--secret", "${cmd: op read op://vault/secret}"
],
"env": {
"API_TOKEN": "${cmd: aws ssm get-parameter --name /app/token --query Parameter.Value --output text}",
"DB_URL": "postgresql://user:${DB_PASSWORD}@localhost/myapp",
"DB_PASSWORD": "${cmd: op read op://vault/db/password}",
"FALLBACK_VAR": null
},
"dev": {
"enabled": true,
"watch": ["src/**/*.js", "**/*.json"],
"cwd": "/absolute/path/to/server/directory"
}
}
}
}
Remote Server
{
"mcpServers": {
"remote-server": {
"url": "https://${PRIVATE_DOMAIN}/mcp",
"headers": {
"Authorization": "Bearer ${cmd: op read op://vault/api/token}",
"X-Custom-Header": "${CUSTOM_VALUE}"
}
}
}
}
Configuration Options
MCP Hub supports both STDIO servers and remote servers (streamable-http/SSE). The server type is automatically detected from the configuration. All fields support the universal ${} placeholder syntax.
STDIO Server Options
For running script-based MCP servers locally:
- command: Command to start the MCP server executable (supports
${VARIABLE}and${cmd: command}) - args: Array of command line arguments (supports
${VARIABLE}and${cmd: command}placeholders) - env: Environment variables with placeholder resolution and system fallback
- cwd: The cwd for process spawning the MCP server
- dev: Development mode configuration (optional)
- enabled: Enable/disable dev mode (default: true)
- watch: Array of glob patterns to watch for changes (default: ["/*.js", "/.ts", "**/.json"])
- cwd: Required absolute path to the server's working directory for file watching
Global Environment Variables (MCP_HUB_ENV)
MCP Hub will look for the environment variable MCP_HUB_ENV (a JSON string) in its own process environment. If set, all key-value pairs from this variable will be injected into the environment of every managed MCP server (both stdio and remote). This is useful for passing secrets, tokens, or other shared configuration to all servers without repeating them in each server config.
- Server-specific
envfields always override values fromMCP_HUB_ENV. - Example usage:
MCP_HUB_ENV='{"DBUS_SESSION_BUS_ADDRESS":"/run/user/1000/bus","MY_TOKEN":"abc"}' mcp-hub --port 3000 --config path/to/config.json
Remote Server Options
For connecting to remote MCP servers:
- url: Server endpoint URL (supports
${VARIABLE}and${cmd: command}placeholders) - headers: Authentication headers (supports
${VARIABLE}and${cmd: command}placeholders)
Server Type Detection
The server type is determined by:
- STDIO server → Has
commandfield - Remote server → Has
urlfield
Note: A server configuration cannot mix STDIO and remote server fields.
Placeholder Resolution Order
- Commands First:
${cmd: command args}are executed first - Environment Variables:
${VAR}are resolved fromenvobject, thenprocess.env - Fallback:
nullor""values fall back toprocess.env - Multi-pass: Dependencies between variables are resolved automatically
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",
"version": "4.1.1",
"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"
}
]
},
"workspaces": {
"current": "40123",
"allActive": {
"40123": {
"cwd": "/path/to/project-a",
"config_files": ["/home/user/.config/mcphub/global.json", "/path/to/project-a/.mcphub/project.json"],
"pid": 12345,
"port": 40123,
"startTime": "2025-01-17T10:00:00.000Z",
"state": "active",
"activeConnections": 2,
"shutdownStartedAt": null,
"shutdownDelay": null
}
}
}
}
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"
}
Workspace Management
List Active Workspaces
GET /api/workspaces
Response:
{
"workspaces": {
"40123": {
"cwd": "/path/to/project-a",
"config_files": ["/home/user/.config/mcphub/global.json", "/path/to/project-a/.mcphub/project.json"],
"pid": 12345,
"port": 40123,
"startTime": "2025-01-17T10:00:00.000Z",
"state": "active",
"activeConnections": 2,
"shutdownStartedAt": null,
"shutdownDelay": null
},
"40567": {
"cwd": "/path/to/project-b",
"config_files": ["/home/user/.config/mcphub/global.json"],
"pid": 54321,
"port": 40567,
"startTime": "2025-01-17T10:05:00.000Z",
"state": "shutting_down",
"activeConnections": 0,
"shutdownStartedAt": "2025-01-17T10:15:00.000Z",
"shutdownDelay": 600000
}
},
"timestamp": "2024-02-20T05:55:00.000Z"
}
Marketplace Integration
List Available Servers
GET /api/marketplace
Query Parameters:
search: Filter by name, description, or tagscategory: Filter by categorytags: Filter by comma-separated tagssort: Sort by "newest", "stars", or "name"
Response:
{
"servers": [
{
"id": "example-server",
"name": "Example Server",
"description": "Description here",
"author": "example-author",
"url": "https://github.com/user/repo",
"category": "search",
"tags": ["search", "ai"],
"stars": 100,
"featured": true,
"verified": true,
"lastCommit": 1751257963,
"updatedAt": 1751265038
}
],
"timestamp": "2024-02-20T05:55:00.000Z"
}
Get Server Details
POST /api/marketplace/details
Content-Type: application/json
{
"mcpId": "example-server"
}
Response:
{
"server": {
"id": "example-server",
"name": "Example Server",
"description": "Description here",
"author": "example-author",
"url": "https://github.com/user/repo",
"category": "search",
"tags": ["search", "ai"],
"installations": [],
"stars": 100,
"featured": true,
"verified": true,
"lastCommit": 1751257963,
"updatedAt": 1751265038
},
"readmeContent": "# Server Documentation...",
"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": {},
"request_options" : {}
}
Access Resource
POST /api/servers/resources
Content-Type: application/json
{
"server_name": "example-server",
"uri": "resource://uri",
"request_options" : {}
}
Get Prompt
POST /api/servers/prompts
Content-Type: application/json
{
"server_name": "example-server",
"prompt": "prompt_name",
"arguments": {},
"request_options" : {}
}
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:
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"
}
- workspaces_updated - Active workspaces changed
{
"type": "workspaces_updated",
"workspaces": {
"40123": {
"cwd": "/path/to/project-a",
"config_files": ["/home/user/.config/mcphub/global.json", "/path/to/project-a/.mcphub/project.json"],
"pid": 12345,
"port": 40123,
"startTime": "2025-01-17T10:00:00.000Z",
"state": "active",
"activeConnections": 2,
"shutdownStartedAt": null,
"shutdownDelay": null
}
},
"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
/healthendpoint - 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 following XDG Base Directory Specification:
- XDG compliant:
$XDG_STATE_HOME/mcp-hub/logs/mcp-hub.log(typically~/.local/state/mcp-hub/logs/mcp-hub.log) - Legacy fallback:
~/.mcp-hub/logs/mcp-hub.log(for backward compatibility)
Example log entry:
{
"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 messageswarn: Warning conditionsdebug: 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.
Workspace Cache
MCP Hub maintains a global workspace cache to track active instances across different working directories with real-time lifecycle management:
- Cache Location:
$XDG_STATE_HOME/mcp-hub/workspaces.json(typically~/.local/state/mcp-hub/workspaces.json) - Purpose: Prevents port conflicts, enables workspace discovery, and provides real-time lifecycle tracking
- Content: Maps port numbers (as keys) to hub process information with detailed lifecycle state
- Cleanup: Automatically removes stale entries when processes are no longer running
Cache Structure
{
"40123": {
"cwd": "/path/to/project-a",
"config_files": ["/home/user/.config/mcphub/global.json", "/path/to/project-a/.mcphub/project.json"],
"pid": 12345,
"port": 40123,
"startTime": "2025-01-17T10:00:00.000Z",
"state": "active",
"activeConnections": 2,
"shutdownStartedAt": null,
"shutdownDelay": null
},
"40567": {
"cwd": "/path/to/project-b",
"config_files": ["/home/user/.config/mcphub/global.json"],
"pid": 54321,
"port": 40567,
"startTime": "2025-01-17T10:05:00.000Z",
"state": "shutting_down",
"activeConnections": 0,
"shutdownStartedAt": "2025-01-17T10:15:00.000Z",
"shutdownDelay": 600000
}
}
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
MCP Registry
MCP Hub now uses the MCP Registry system for marketplace functionality. This provides:
- Decentralized Server Discovery: Registry hosted on GitHub Pages for better reliability
- Direct GitHub Integration: README documentation fetched directly from repositories
- Enhanced Metadata: Comprehensive server information including stars, categories, and installation instructions
- Better Caching: Improved cache system with 1-hour TTL for frequent updates
- Fallback Support: Automatic fallback to curl when fetch fails (useful for proxy/VPN environments)
The registry is updated regularly with new servers and improvements to existing entries.
Todo
- Implement custom marketplace rather than depending on mcp-marketplace
- TUI like mcphub.nvim
- Web UI for managing servers
Acknowledgements
- ravitemer/mcp-registry - For providing the MCP server marketplace endpoints that power MCP Hub's marketplace integration
