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

| Category | Feature | Support | Notes | |----------|---------|---------|-------| | Transport |||| | | streamable-http | ✅ | Primary transport protocol for remote servers | | | SSE | ✅ | Fallback transport for remote servers | | | STDIO | ✅ | For running local servers | | Authentication |||| | | OAuth 2.0 | ✅ | With PKCE flow | | | Headers | ✅ | For API keys/tokens | | Capabilities |||| | | Tools | ✅ | List tools | | | 🔔 Tool List Changed | ✅ | Real-time updates | | | Resources | ✅ | Full support | | | 🔔 Resource List Changed | ✅ | Real-time updates | | | Resource Templates | ✅ | URI templates | | | Prompts | ✅ | Full support | | | 🔔 Prompts List Changed | ✅ | Real-time updates | | | Roots | ❌ | Not supported | | | Sampling | ❌ | Not supported | | | Completion | ❌ | Not supported | | Marketplace |||| | | Server Discovery | ✅ | Browse available servers | | | Installation | ✅ | Auto configuration | | Real-time |||| | | Status Updates | ✅ | Server & connection state | | | Capability Updates | ✅ | Automatic refresh | | | Event Streaming to clients | ✅ | SSE-based | | | Auto Reconnection | ✅ | With backoff | | Development |||| | | Hot Reload | ✅ | Auto restart a MCP server on file changes with dev mode | | Configuration |||| | | ${} Syntax | ✅ | Environment variables and command execution across all fields | | | VS Code Compatibility | ✅ | Support for servers key, ${env:}, ${input:}, predefined variables | | | JSON5 Support | ✅ | Comments and trailing commas in configuration files |

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
• 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)
• null or "" - Falls back to process.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).