MCP Hub

MCP Hub acts as a central coordinator for MCP servers and clients, providing two key interfaces:

1. Management Interface (/api/*): Manage multiple MCP servers through a unified REST API and web UI
2. 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__search vs database__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:

• mcpServers sections are merged (server definitions from later files override earlier ones)
• Other top-level properties are completely replaced by later files